Nested Menu

An accessible dropdown and context menu that is used to display a list of actions or options that a user can choose.

1.40.0 (latest)Visualize Logic View Source

Features

Supports items, labels, groups of items
Focus is fully managed using aria-activedescendant pattern
Typeahead to allow focusing items by typing text
Keyboard navigation support including arrow keys, home/end, page up/down

Installation

Install the menu package:

Anatomy

Check the menu anatomy and part names.

Each part includes a data-part attribute to help identify them in the DOM.

Usage

Import the menu package:

import * as menu from "@zag-js/menu"

The menu package exports two key functions:

machine - Behavior logic for the menu.
connect - Maps behavior to JSX props and event handlers.

Pass a unique id to useMachine so generated element ids stay predictable.

Then use the framework integration helpers:

Destructure the service returned from useMachine.
Use the exposed setParent and setChild functions provided by the menu's connect function to assign the parent and child menus respectively.
Create trigger items using api.getTriggerItemProps(...).

When building nested menus, you'll need to use:

setParent(...) - Registers the parent menu on the child menu.
setChild(...) - Registers the child menu on the parent menu.

import * as menu from "@zag-js/menu"
import { useMachine, normalizeProps, Portal } from "@zag-js/react"
import { useEffect, useId } from "react"

export function NestedMenu() {
  // Level 1 - File Menu
  const fileMenuService = useMachine(menu.machine, {
    id: useId(),
    "aria-label": "File",
  })

  const fileMenu = menu.connect(fileMenuService, normalizeProps)

  // Level 2 - Share Menu
  const shareMenuService = useMachine(menu.machine, {
    id: useId(),
    "aria-label": "Share",
  })

  const shareMenu = menu.connect(shareMenuService, normalizeProps)

  useEffect(() => {
    setTimeout(() => {
      fileMenu.setChild(shareMenuService)
      shareMenu.setParent(fileMenuService)
    })
  }, [])

  // Share menu trigger
  const shareMenuTriggerProps = fileMenu.getTriggerItemProps(shareMenu)

  return (
    <>
      <button {...fileMenu.getTriggerProps()}>Click me</button>

      <Portal>
        <div {...fileMenu.getPositionerProps()}>
          <ul {...fileMenu.getContentProps()}>
            <li {...fileMenu.getItemProps({ value: "new-tab" })}>New tab</li>
            <li {...fileMenu.getItemProps({ value: "new-win" })}>New window</li>
            <li {...shareMenuTriggerProps}>Share</li>
            <li {...fileMenu.getItemProps({ value: "print" })}>Print...</li>
            <li {...fileMenu.getItemProps({ value: "help" })}>Help</li>
          </ul>
        </div>
      </Portal>

      <Portal>
        <div {...shareMenu.getPositionerProps()}>
          <ul {...shareMenu.getContentProps()}>
            <li {...shareMenu.getItemProps({ value: "messages" })}>Messages</li>
            <li {...shareMenu.getItemProps({ value: "airdrop" })}>Airdrop</li>
            <li {...shareMenu.getItemProps({ value: "whatsapp" })}>WhatsApp</li>
          </ul>
        </div>
      </Portal>
    </>
  )
}

import * as menu from "@zag-js/menu"
import { normalizeProps, useMachine } from "@zag-js/solid"
import { createMemo, createUniqueId, onMount } from "solid-js"
import { Portal } from "solid-js/web"

export default function Page() {
  // Level 1 - File Menu
  const fileService = useMachine(menu.machine, {
    "aria-label": "File",
    id: createUniqueId(),
  })

  const fileMenu = createMemo(() => menu.connect(fileService, normalizeProps))

  // Level 2 - Share Menu
  const shareService = useMachine(menu.machine, {
    "aria-label": "Share",
    id: createUniqueId(),
  })

  const shareMenu = createMemo(() => menu.connect(shareService, normalizeProps))

  onMount(() => {
    setTimeout(() => {
      fileMenu().setChild(shareService)
      shareMenu().setParent(fileService)
    })
  })

  // Share menu trigger
  const shareMenuTriggerProps = createMemo(() =>
    fileMenu().getTriggerItemProps(shareMenu()),
  )

  return (
    <>
      <button {...fileMenu().getTriggerProps()}>Click me</button>

      <Portal>
        <div {...fileMenu().getPositionerProps()}>
          <ul {...fileMenu().getContentProps()}>
            <li {...fileMenu().getItemProps({ value: "new-tab" })}>New tab</li>
            <li {...fileMenu().getItemProps({ value: "new-win" })}>
              New window
            </li>
            <li {...shareMenuTriggerProps()}>Share</li>
            <li {...fileMenu().getItemProps({ value: "print" })}>Print...</li>
            <li {...fileMenu().getItemProps({ value: "help" })}>Help</li>
          </ul>
        </div>
      </Portal>

      <Portal>
        <div {...shareMenu().getPositionerProps()}>
          <ul {...shareMenu().getContentProps()}>
            <li {...shareMenu().getItemProps({ value: "messages" })}>
              Messages
            </li>
            <li {...shareMenu().getItemProps({ value: "airdrop" })}>Airdrop</li>
            <li {...shareMenu().getItemProps({ value: "whatsapp" })}>
              WhatsApp
            </li>
          </ul>
        </div>
      </Portal>
    </>
  )
}

<script setup>
  import * as menu from "@zag-js/menu"
  import { normalizeProps, useMachine } from "@zag-js/vue"
  import { computed, onMounted, Teleport } from "vue"

  // Level 1 - File Menu
  const fileService = useMachine(menu.machine, {
    id: "1",
    "aria-label": "File",
  })

  const fileMenu = computed(() => menu.connect(fileService, normalizeProps))

  // Level 2 - Share Menu
  const shareService = useMachine(menu.machine, {
    id: "2",
    "aria-label": "Share",
  })

  const shareMenu = computed(() => menu.connect(shareService, normalizeProps))

  onMounted(() => {
    setTimeout(() => {
      fileMenu.value.setChild(shareService)
      shareMenu.value.setParent(fileService)
    })
  })

  // Share menu trigger
  const shareMenuTriggerProps = computed(() =>
    fileMenu.value.getTriggerItemProps(shareMenu.value),
  )
</script>

<template>
  <button v-bind="fileMenu.getTriggerProps()">Click me</button>

  <Teleport to="body">
    <div v-bind="fileMenu.getPositionerProps()">
      <ul ref="fileMenuRef" v-bind="fileMenu.getContentProps()">
        <li v-bind="fileMenu.getItemProps({ value: 'new-tab' })">New tab</li>
        <li v-bind="fileMenu.getItemProps({ value: 'new-win' })">New window</li>
        <li v-bind="shareMenuTriggerProps">Share</li>
        <li v-bind="fileMenu.getItemProps({ value: 'print' })">Print...</li>
        <li v-bind="fileMenu.getItemProps({ value: 'help' })">Help</li>
      </ul>
    </div>
  </Teleport>

  <Teleport to="body">
    <div v-bind="shareMenu.getPositionerProps()">
      <ul ref="shareMenuRef" v-bind="shareMenu.getContentProps()">
        <li v-bind="shareMenu.getItemProps({ value: 'messages' })">Messages</li>
        <li v-bind="shareMenu.getItemProps({ value: 'airdrop' })">Airdrop</li>
        <li v-bind="shareMenu.getItemProps({ value: 'whatsapp' })">WhatsApp</li>
      </ul>
    </div>
  </Teleport>
</template>

<script lang="ts">
  import * as menu from "@zag-js/menu"
  import { portal, normalizeProps, useMachine } from "@zag-js/svelte"
  import { onMount } from "svelte"

  const id = $props.id()

  // Level 1 - File Menu
  const fileService = useMachine(menu.machine, ({ id: `${id}-1`, "aria-label": "File" }))

  const fileMenu = $derived(menu.connect(fileService, normalizeProps))

  // Level 2 - Share Menu
  const shareService = useMachine(menu.machine, ({ id: `${id}-2`, "aria-label": "Share" }))

  const shareMenu = $derived(menu.connect(shareService, normalizeProps))

  onMount(() => {
    fileMenu.setChild(shareService)
    shareMenu.setParent(fileService)
  })

  // Share menu trigger
  const shareMenuTriggerProps = $derived(fileMenu.getTriggerItemProps(shareMenu))
</script>

<button {...fileMenu.getTriggerProps()}>Click me</button>

<div use:portal {...fileMenu.getPositionerProps()}>
  <ul {...fileMenu.getContentProps()}>
    <li {...fileMenu.getItemProps({ value: "new-tab" })}>New tab</li>
    <li {...fileMenu.getItemProps({ value: "new-win" })}>New window</li>
    <li {...shareMenuTriggerProps}>Share</li>
    <li {...fileMenu.getItemProps({ value: "print" })}>Print...</li>
    <li {...fileMenu.getItemProps({ value: "help" })}>Help</li>
  </ul>
</div>

<div use:portal {...shareMenu.getPositionerProps()}>
  <ul {...shareMenu.getContentProps()}>
    <li {...shareMenu.getItemProps({ value: "messages" })}>Messages</li>
    <li {...shareMenu.getItemProps({ value: "airdrop" })}>Airdrop</li>
    <li {...shareMenu.getItemProps({ value: "whatsapp" })}>WhatsApp</li>
  </ul>
</div>

Controlling open state

Use open and onOpenChange to control the open state.

const service = useMachine(menu.machine, {
  open,
  onOpenChange(details) {
    // details => { open: boolean }
    setOpen(details.open)
  },
})

Default open state

Use defaultOpen for an uncontrolled initial state.

const service = useMachine(menu.machine, {
  defaultOpen: true,
})

Listening for highlighted changes

Use onHighlightChange to react when keyboard or pointer highlight changes.

const service = useMachine(menu.machine, {
  onHighlightChange(details) {
    // details => { highlightedValue: string | null }
    console.log(details.highlightedValue)
  },
})

Setting the initial highlighted item

Use defaultHighlightedValue to set the initially highlighted menu item.

const service = useMachine(menu.machine, {
  defaultHighlightedValue: "copy",
})

Listening for item selection

Use onSelect to react when an item is selected.

const service = useMachine(menu.machine, {
  onSelect(details) {
    // details => { value: string }
    console.log(details.value)
  },
})

Positioning submenus

Use positioning to configure submenu placement.

const service = useMachine(menu.machine, {
  positioning: { placement: "right-start" },
})

Styling guide

Each menu part includes a data-part attribute you can target in CSS.

Highlighted item state

When an item is highlighted, via keyboard navigation or pointer, it is given a data-highlighted attribute.

[data-part="item"][data-highlighted] {
  /* styles for highlighted state */
}

[data-part="item"][data-type="radio|checkbox"][data-highlighted] {
  /* styles for highlighted state */
}

Disabled item state

When an item or an option item is disabled, it is given a data-disabled attribute.

[data-part="item"][data-disabled] {
  /* styles for disabled state */
}

[data-part="item"][data-type="radio|checkbox"][data-disabled] {
  /* styles for disabled state */
}

Using arrows

When using arrows within the menu, you can style it using CSS variables.

[data-part="arrow"] {
  --arrow-size: 20px;
  --arrow-background: red;
}

Checked option item state

When an option item is checked, it is given a data-state attribute.

[data-part="item"][data-type="radio|checkbox"][data-state="checked"] {
  /* styles for checked state */
}

Methods and Properties

Machine Context

The menu machine exposes the following context properties:

idsPartial<{ trigger: string | ((value?: string | undefined) => string); contextTrigger: string | ((value?: string | undefined) => string); content: string; groupLabel: (id: string) => string; group: (id: string) => string; positioner: string; arrow: string; }> | undefinedThe ids of the elements in the menu. Useful for composition.
defaultHighlightedValuestring | null | undefinedThe initial highlighted value of the menu item when rendered. Use when you don't need to control the highlighted value of the menu item.
highlightedValuestring | null | undefinedThe controlled highlighted value of the menu item.
onHighlightChange((details: HighlightChangeDetails) => void) | undefinedFunction called when the highlighted menu item changes.
onSelect((details: SelectionDetails) => void) | undefinedFunction called when a menu item is selected.
anchorPointanyThe positioning point for the menu. Can be set by the context menu trigger or the button trigger.
loopFocusboolean | undefinedWhether to loop the keyboard navigation.
positioninganyThe options used to dynamically position the menu
closeOnSelectboolean | undefinedWhether to close the menu when an option is selected
aria-labelstring | undefinedThe accessibility label for the menu
openboolean | undefinedThe controlled open state of the menu
onOpenChange((details: OpenChangeDetails) => void) | undefinedFunction called when the menu opens or closes
defaultOpenboolean | undefinedThe initial open state of the menu when rendered. Use when you don't need to control the open state of the menu.
typeaheadboolean | undefinedWhether the pressing printable characters should trigger typeahead navigation
compositeboolean | undefinedWhether the menu is a composed with other composite widgets like a combobox or tabs
navigate((details: NavigateDetails) => void) | null | undefinedFunction to navigate to the selected item if it's an anchor element
triggerValuestring | null | undefinedThe controlled trigger value
defaultTriggerValuestring | null | undefinedThe initial trigger value when rendered. Use when you don't need to control the trigger value.
onTriggerValueChange((details: TriggerValueChangeDetails) => void) | undefinedFunction called when the trigger value changes.
dir"ltr" | "rtl" | undefinedThe document's text/writing direction.
idstringThe unique identifier of the machine.
getRootNode(() => ShadowRoot | Node | Document) | undefinedA root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

Machine API

The menu api exposes the following methods:

openbooleanWhether the menu is open
setOpen(open: boolean) => voidFunction to open or close the menu
triggerValuestring | nullThe trigger value
setTriggerValue(value: string | null) => voidFunction to set the trigger value
highlightedValuestring | nullThe id of the currently highlighted menuitem
setHighlightedValue(value: string) => voidFunction to set the highlighted menuitem
setParent(parent: Service<MenuSchema>) => voidFunction to register a parent menu. This is used for submenus
setChild(child: Service<MenuSchema>) => voidFunction to register a child menu. This is used for submenus
reposition(options?: any) => voidFunction to reposition the popover
getOptionItemState(props: OptionItemProps) => OptionItemStateReturns the state of the option item
getItemState(props: ItemProps) => ItemStateReturns the state of the menu item
addItemListener(props: ItemListenerProps) => VoidFunction | undefinedSetup the custom event listener for item selection event

Data Attributes

ContextTrigger

data-scope

data-part

context-trigger

data-value

The value of the item

data-current

Present when current

data-state

"open" | "closed"

Trigger

data-scope

data-part

trigger

data-placement

The placement of the trigger

data-value

The value of the item

data-current

Present when current

data-state

"open" | "closed"

Indicator

data-scope

data-part

indicator

data-state

"open" | "closed"

Content

data-scope

data-part

content

data-state

"open" | "closed"

data-nested

data-has-nested

data-placement

The placement of the content

Item

data-scope

data-part

item

data-disabled

Present when disabled

data-highlighted

Present when highlighted

data-value

The value of the item

data-valuetext

The human-readable value

OptionItem

data-scope

data-part

option-item

data-type

The type of the item

data-value

The value of the item

data-state

"checked" | "unchecked"

data-disabled

Present when disabled

data-highlighted

Present when highlighted

data-valuetext

The human-readable value

ItemIndicator

data-scope

data-part

item-indicator

data-disabled

Present when disabled

data-highlighted

Present when highlighted

data-state

"checked"

ItemText

data-scope

data-part

item-text

data-disabled

Present when disabled

data-highlighted

Present when highlighted

data-state

"checked"

CSS Variables

Arrow

--arrow-size

The size of the arrow

--arrow-size-half

Half the size of the arrow

--arrow-background

Use this variable to style the arrow background

--arrow-offset

The offset position of the arrow

Positioner

--reference-width

The width of the reference element

--reference-height

The height of the root

--available-width

The available width in viewport

--available-height

The available height in viewport

--x

The x position for transform

--y

The y position for transform

--z-index

The z-index value

--transform-origin

The transform origin for animations

Content

--layer-index

The index of the dismissable in the layer stack

--nested-layer-count

The number of nested menus

Backdrop

--layer-index

The index of the dismissable in the layer stack

Accessibility

Uses aria-activedescendant pattern to manage focus movement among menu items.

Keyboard Interactions

Space
Opens/closes the nested menu.
Enter
Opens/closes the nested menu.
ArrowDown
Moves focus to the next item.
ArrowUp
Moves focus to the previous item.
ArrowRight
Opens the nested menu.
ArrowLeft
Closes the nested menu.
Esc
Closes the nested menu and moves focus to the parent menu item.

Edit this page on GitHub

Nested Menu

Installation

Anatomy

Usage

Controlling open state

Default open state

Listening for highlighted changes

Setting the initial highlighted item

Listening for item selection

Positioning submenus

Styling guide

Highlighted item state

Disabled item state

Using arrows

Checked option item state

Methods and Properties

Machine Context

Machine API

Data Attributes

CSS Variables

Accessibility

Keyboard Interactions

On this page