Menu

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

Features

Support for 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

To use the menu machine in your project, run the following command in your command line:

This command will install the framework agnostic menu logic and the reactive utilities for your framework of choice.

Anatomy

To set up the menu correctly, you'll need to understand its anatomy and how we name its parts.

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

On a high level, the menu consists of:

Trigger: The element that toggles the menu.
Positioner: The element that positions the menu dynamically.
Content: The element that contains the menu items and groups.
Item: The menu item used to trigger an action.

The optional parts include:

Option Item: The menu item that acts as a radio or checkbox.
Context Trigger: The trigger for the menu item.
Separator: The element that is used to visually separate menu items.

Usage

First, import the menu package into your project

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

The menu package exports two key functions:

machine — The state machine logic for the menu widget.
connect — The function that translates the machine's state to JSX attributes and event handlers.

You'll need to provide a unique id to the useMachine hook. This is used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the menu machine in your project 🔥

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

export function Menu() {
  const [state, send] = useMachine(menu.machine({ id: "1", "aria-label": "File" }))
  
  const api = menu.connect(state, send, normalizeProps)

  return (
    <div>
      <button {...api.triggerProps}>
        Actions <span aria-hidden>▾</span>
      </button>
      <div {...api.positionerProps}>
        <ul {...api.contentProps}>
          <li {...api.getItemProps({ id: "edit" })}>Edit</li>
          <li {...api.getItemProps({ id: "duplicate" })}>Duplicate</li>
          <li {...api.getItemProps({ id: "delete" })}>Delete</li>
          <li {...api.getItemProps({ id: "export" })}>Export...</li>
        </ul>
      </div>
    </div>
  )
}

import * as menu from "@zag-js/menu"
import { normalizeProps, useMachine } from "@zag-js/vue"
import { computed, defineComponent, h, Fragment } from "vue"

export default defineComponent({
  name: "Menu",
  setup() {
    const [state, send] = useMachine(
      menu.machine({ id: "1", "aria-label": "File" }),
    )

    const apiRef = computed(() =>
      menu.connect(state.value, send, normalizeProps),
    )
    return () => {
      const api = apiRef.value
      return (
        <div>
          <button {...api.triggerProps}>
            Actions <span aria-hidden>▾</span>
          </button>
          <div {...api.positionerProps}>
            <ul {...api.contentProps}>
              <li {...api.getItemProps({ id: "edit" })}>Edit</li>
              <li {...api.getItemProps({ id: "duplicate" })}>Duplicate</li>
              <li {...api.getItemProps({ id: "delete" })}>Delete</li>
              <li {...api.getItemProps({ id: "export" })}>Export...</li>
            </ul>
          </div>
        </div>
      )
    }
  },
})

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

const [state, send] = useMachine(menu.machine({ id: "menu", "aria-label": "File" }));
const api = computed(() => menu.connect(state.value, send, normalizeProps));
</script>

<template>
  <div ref="ref">
    <button v-bind="api.triggerProps">
      Actions <span aria-hidden>▾</span>
    </button>
    <div v-bind="api.positionerProps">
      <ul v-bind="api.contentProps">
        <li v-bind="api.getItemProps({ id: 'edit' })">Edit</li>
        <li v-bind="api.getItemProps({ id: 'duplicate' })">Duplicate</li>
        <li v-bind="api.getItemProps({ id: 'delete' })">Delete</li>
        <li v-bind="api.getItemProps({ id: 'export' })">Export...</li>
      </ul>
    </div>
  </div>
</template>

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

export function Menu() {
  const [state, send] = useMachine(
    menu.machine({ id: createUniqueId(), "aria-label": "File" }),
  )

  const api = createMemo(() => menu.connect(state, send, normalizeProps))

  return (
    <div>
      <button {...api().triggerProps}>
        Actions <span aria-hidden>▾</span>
      </button>
      <div {...api().positionerProps}>
        <ul {...api().contentProps}>
          <li {...api().getItemProps({ id: "edit" })}>Edit</li>
          <li {...api().getItemProps({ id: "duplicate" })}>Duplicate</li>
          <li {...api().getItemProps({ id: "delete" })}>Delete</li>
          <li {...api().getItemProps({ id: "export" })}>Export...</li>
        </ul>
      </div>
    </div>
  )
}

Listening to item selection

Pass onSelect to the machine's context to perform some custom logic when an item is selected. When an item is selected, the machine invokes the onSelect callback. This callback is invoked with the value of the item.

const [state, send] = useMachine(
  menu.machine({
    values: { order: "", type: [] },
    onSelect(value) {
      // value => "nigeria"
      console.log("selected value is ", value)
    },
  }),
)

Methods and Properties

The menu's api exposes the following methods:

isOpen — Whether the menu is open.
open(...) — Function to open the menu.
close(...) — Function to close the menu.
activeId — The id of the active menu item.
setActiveId(...) — Function to set the value active menu item.
isOptionChecked(...) — Function to check whether an option item is checked.

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

setParent(...) — Function to register a parent menu's machine in the child menu's context.
setChild(...) — Function to register a child menu's machine in the parent menu's context.

When the number of menu items gets much, it might be useful to group related menu items. To achieve this:

Wrap the menu items within an element.
Spread the api.groupProps(...) JSX properties unto the element, providing an id.
Render a label for the menu group, providing the id of the group element.

//...
<div {...api.contentProps}>
  {/* ... */}
  <hr {...api.separatorProps} />
  <p {...api.getLabelProps({ htmlFor: "account" })}>Accounts</p>
  <div {...api.getGroupProps({ id: "account" })}>
    <button {...api.getItemProps({ id: "account-1" })}>Account 1</button>
    <button {...api.getItemProps({ id: "account-2" })}>Account 2</button>
  </div>
</div>
//...

Checkbox and Radio option items

To use checkbox or radio option items, you'll need to:

Add a values property to the machine's context whose value is an object describing the state of the option items.
Use the api.getOptionItemProps(...) function to get the props for the option item.
Optionally use the api.isOptionChecked(...) function to check whether an option item is checked.

A common requirement for the option item that you pass the name, value and type properties.

name — The property key in the values context that this option is for.
type — The type of option item. Either "checkbox" or "radio".
value — The value of the option item.

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

const data = {
  order: [
    { label: "Ascending", id: "asc" },
    { label: "Descending", id: "desc" },
    { label: "None", id: "none" },
  ],
  type: [
    { label: "Email", id: "email" },
    { label: "Phone", id: "phone" },
    { label: "Address", id: "address" },
  ],
}

export function Menu() {
  const [state, send] = useMachine(
    menu.machine({
      id: "1",
      "aria-label": "Sort by",
      values: { order: "", type: [] },
    }),
  )

  const api = menu.connect(state, send, normalizeProps)

  return (
    <>
      <button {...api.triggerProps}>Trigger</button>
      <div {...api.positionerProps}>
        <div {...api.contentProps}>
          {data.order.map((item) => {
            const option = { type: "radio", name: "order", value: item.id }
            return (
              <div key={item.id} {...api.getOptionItemProps(option)}>
                {api.isOptionChecked(option) ? "✅" : null} {item.label}
              </div>
            )
          })}
          <hr {...api.separatorProps} />
          {data.type.map((item) => {
            const option = { type: "checkbox", name: "type", value: item.id }
            return (
              <div key={item.id} {...api.getOptionItemProps(option)}>
                {api.isOptionChecked(option) ? "✅" : null} {item.label}
              </div>
            )
          })}
        </div>
      </div>
    </>
  )
}

import * as menu from "@zag-js/menu"
import { normalizeProps, useMachine } from "@zag-js/vue"
import { computed, defineComponent, h, Fragment } from "vue"

export default defineComponent({
  name: "Menu",
  setup() {
    const [state, send] = useMachine(
      menu.machine({
        id: "1",
        "aria-label": "Sort by",
        values: { order: "", type: [] },
      }),
    )

    const apiRef = computed(() =>
      menu.connect(state.value, send, normalizeProps),
    )

    return () => {
      const api = apiRef.value
      return (
        <>
          <button {...api.triggerProps}>Trigger</button>
          <div {...api.positionerProps}>
            <div {...api.contentProps}>
              {data.order.map((item) => {
                const option = { type: "radio", name: "order", value: item.id }
                return (
                  <div key={item.id} {...api.getOptionItemProps(option)}>
                    {api.isOptionChecked(option) ? "✅" : null} {item.label}
                  </div>
                )
              })}
              <hr {...api.separatorProps} />
              {data.type.map((item) => {
                const option = {
                  type: "checkbox",
                  name: "type",
                  value: item.id,
                }
                return (
                  <div key={item.id} {...api.getOptionItemProps(option)}>
                    {api.isOptionChecked(option) ? "✅" : null} {item.label}
                  </div>
                )
              })}
            </div>
          </div>
        </>
      )
    }
  },
})

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

const [state, send] = useMachine(
  menu.machine({
    id: "1",
    "aria-label": "Sort by",
    values: { order: "", type: [] },
  })
);

const api = computed(() => menu.connect(state.value, send, normalizeProps));
const orderOptions = data.order.map((item) => ({
  ...item,
  option: { type: "radio", name: "order", value: item.id },
}));
const typeOptions = data.type.map((item) => ({
  ...item,
  option: { type: "checkbox", name: "type", value: item.id },
}));
</script>

<template>
  <button ref="ref" v-bind="api.triggerProps">Trigger</button>
  <div v-bind="api.positionerProps">
    <div v-bind="api.contentProps">
      <div
        v-for="item in orderOptions"
        :key="item.id"
        v-bind="api.getOptionItemProps(item.option)"
      >
        {{ api.isOptionChecked(item.option) ? "✅" : null }} {{ item.label }}
      </div>
      <hr v-bind="api.separatorProps" />

      <div
        v-for="item in typeOptions"
        :key="item.id"
        v-bind="api.getOptionItemProps(item.option)"
      >
        {{ api.isOptionChecked(item.option) ? "✅" : null }} {{ item.label }}
      </div>
    </div>

  </div>
</template>

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

export function Menu() {
  const [state, send] = useMachine(
    menu.machine({
      id: createUniqueId(),
      "aria-label": "Sort by",
      values: { order: "", type: [] },
    }),
  )

  const api = createMemo(() => menu.connect(state, send, normalizeProps))

  return (
    <>
      <button {...api().triggerProps}>
        Trigger
      </button>
      <div {...api().positionerProps}>
        <div {...api().contentProps}>
          <For each={data.order}>
            {(item) => {
              const option = { type: "radio", name: "order", value: item.id }
              return (
                <div {...api().getOptionItemProps(option)}>
                  {api().isOptionChecked(option) ? "✅" : null} {item.label}
                </div>
              )
            }}
          </For>
          <hr  {...api.separatorProps/>
          <For each={data.type}>
            {(item) => {
              const option = { type: "checkbox", name: "type", value: item.id }
              return (
                <div {...api().getOptionItemProps(option)}>
                  {api().isOptionChecked(option) ? "✅" : null} {item.label}
                </div>
              )
            }}
          </For>
        </div>
      </div>
    </>
  )
}

The machine invokes an onValueChange callback when an radio or checkbox option checked state changes. This callback is invoked with the name of the option and its new value.

const [state, send] = useMachine(
  menu.machine({
    values: { order: "", type: [] },
    onValueChange(data) {
      // data => { name: string, value: string | string[] }
      console.log("values changed", data.value)
    },
  }),
)

Styling guide

Earlier, we mentioned that each menu part has a data-part attribute added to them to select and style them in the DOM.

Open and closed state

When the menu is open or closed, the content and trigger parts will have the data-state attribute.

[data-part="content"][data-state="open|closed"] {
  /* styles for open or closed state */
}

[data-part="trigger"][data-state="open|closed"] {
  /* styles for open or closed state */
}

Focused item state

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

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

[data-part="option-item"][data-focus] {
  /* styles for focused 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="option-item"][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-checked attribute.

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

Methods and Properties

The menu's api method exposes the following methods:

isOpenbooleanWhether the menu is open

open() => voidFunction to open the menu

close() => voidFunction to close the menu

highlightedIdstringThe id of the currently highlighted menuitem

setHighlightedId(id: string) => voidFunction to set the highlighted menuitem

setParent(parent: Service) => voidFunction to register a parent menu. This is used for submenus

setChild(child: Service) => voidFunction to register a child menu. This is used for submenus

valueRecord<string, string | string[]>The value of the menu options item

setValue(name: string, value: any) => voidFunction to set the value of the menu options item

isOptionChecked(opts: OptionItemProps) => booleanFunction to check if an option is checked

setPositioning(options?: Partial<PositioningOptions>) => voidFunction to reposition the popover

Edit this page on GitHub

Installation

Anatomy

Usage

Listening to item selection

Methods and Properties

Grouping menu items

Checkbox and Radio option items

Styling guide

Open and closed state

Focused item state

Disabled item state

Using arrows

Checked option item state

Methods and Properties

On this page