{"slug":"context-menu","title":"Context Menu","description":"Using the menu machine for nested menus in your project.","contentType":"component","framework":"react","content":"An accessible dropdown and context menu that is used to display a list of\nactions or options that a user can choose when a trigger element is\nright-clicked or long pressed.\n\n## Resources\n\n\n[Latest version: v1.31.0](https://www.npmjs.com/package/@zag-js/menu)\n[Logic Visualizer](https://zag-visualizer.vercel.app/menu)\n[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/menu)\n\n\n\n**Features**\n\n- Support for items, labels, groups of items\n- Focus is fully managed using `aria-activedescendant` pattern\n- Typeahead to allow focusing items by typing text\n- Keyboard navigation support including arrow keys, home/end, page up/down\n\n## Installation\n\nTo use the menu machine in your project, run the following command in your\ncommand line:\n\n```bash\nnpm install @zag-js/menu @zag-js/react\n# or\nyarn add @zag-js/menu @zag-js/react\n```\n\n## Anatomy\n\nTo set up the menu correctly, you'll need to understand its anatomy and how we\nname its parts.\n\n> Each part includes a `data-part` attribute to help identify them in the DOM.\n\n\n\n## Usage\n\nFirst, import the menu package into your project\n\n```jsx\nimport * as menu from \"@zag-js/menu\"\n```\n\nThe menu package exports two key functions:\n\n- `machine` — The state machine logic for the menu widget.\n- `connect` — The function that translates the machine's state to JSX attributes\n  and event handlers.\n\n> You'll need to provide a unique `id` to the `useMachine` hook. This is used to\n> ensure that every part has a unique identifier.\n\nNext, import the required hooks and functions for your framework and use the\nmenu machine in your project 🔥\n\nTo show the menu when a trigger element is right-clicked, use the\n`contextTriggerProps` provided by the menu's connect function.\n\nContext menu's are also opened during a long-press of roughly `700ms` when the\npointer is pen or touch.\n\n```jsx\nimport * as menu from \"@zag-js/menu\"\nimport { useMachine, normalizeProps } from \"@zag-js/react\"\n\nexport function ContextMenu() {\n  const service = useMachine(menu.machine, { id: \"1\" })\n  const api = menu.connect(service, normalizeProps)\n\n  return (\n    <div>\n      <div {...api.getContextTriggerProps()}>\n        <div>Open context menu</div>\n      </div>\n      <div {...api.getPositionerProps()}>\n        <ul {...api.getContentProps()}>\n          <li {...api.getItemProps({ value: \"edit\" })}>Edit</li>\n          <li {...api.getItemProps({ value: \"duplicate\" })}>Duplicate</li>\n          <li {...api.getItemProps({ value: \"delete\" })}>Delete</li>\n          <li {...api.getItemProps({ value: \"export\" })}>Export...</li>\n        </ul>\n      </div>\n    </div>\n  )\n}\n```\n\n## Styling guide\n\nEarlier, we mentioned that each menu part has a `data-part` attribute added to\nthem to select and style them in the DOM.\n\n### Highlighted item state\n\nWhen an item is highlighted, via keyboard navigation or pointer, it is given a\n`data-highlighted` attribute.\n\n```css\n[data-part=\"item\"][data-highlighted] {\n  /* styles for highlighted state */\n}\n\n[data-part=\"item\"][data-type=\"radio|checkbox\"][data-highlighted] {\n  /* styles for highlighted state */\n}\n```\n\n### Disabled item state\n\nWhen an item or an option item is disabled, it is given a `data-disabled`\nattribute.\n\n```css\n[data-part=\"item\"][data-disabled] {\n  /* styles for disabled state */\n}\n\n[data-part=\"item\"][data-type=\"radio|checkbox\"][data-disabled] {\n  /* styles for disabled state */\n}\n```\n\n### Using arrows\n\nWhen using arrows within the menu, you can style it using css variables.\n\n```css\n[data-part=\"arrow\"] {\n  --arrow-size: 20px;\n  --arrow-background: red;\n}\n```\n\n### Checked option item state\n\nWhen an option item is checked, it is given a `data-state` attribute.\n\n```css\n[data-part=\"item\"][data-type=\"radio|checkbox\"][data-state=\"checked\"] {\n  /* styles for checked state */\n}\n```\n\n## Methods and Properties\n\n### Machine Context\n\nThe menu machine exposes the following context properties:\n\n<ContextTable name=\"menu\" />\n\n### Machine API\n\nThe menu `api` exposes the following methods:\n\n<ApiTable name=\"menu\" />\n\n### Data Attributes\n\n<DataAttrTable name=\"menu\" />\n\n### CSS Variables\n\n<CssVarTable name=\"menu\" />\n\n## Accessibility\n\nUses\n[aria-activedescendant](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-descendant/)\npattern to manage focus movement among menu items.\n\n### Keyboard Interactions\n\n**`Space`**\nDescription: Activates/Selects the highlighted item\n\n**`Enter`**\nDescription: Activates/Selects the highlighted item\n\n**`ArrowDown`**\nDescription: Highlights the next item in the menu\n\n**`ArrowUp`**\nDescription: Highlights the previous item in the menu\n\n**`ArrowRight + ArrowLeft`**\nDescription: When focus is on trigger, opens or closes the submenu depending on reading direction.\n\n**`Esc`**\nDescription: Closes the context menu","package":"@zag-js/menu","editUrl":"https://github.com/chakra-ui/zag/edit/main/website/data/components/context-menu.mdx"}