<ui:menu.root>
    <ui:menu.trigger>Open Menu</ui:menu.trigger>
    <ui:menu.content>
        <ui:menu.item value="new-file">New File</ui:menu.item>
        <ui:menu.item value="new-window">New Window</ui:menu.item>
        <ui:menu.separator />
        <ui:menu.item value="settings">Settings</ui:menu.item>
    </ui:menu.content>
</ui:menu.root>

Features

Items, labels and groups of items
Checkbox and radio items
Submenus
Context menu and several triggers for one menu
Focus managed with aria-activedescendant
Typeahead to focus items by typing
Keyboard navigation with arrow keys, Home, End and submenus

Anatomy

    
    
            <primitives:menu.root>
    <primitives:menu.trigger>
        <primitives:menu.indicator />
    </primitives:menu.trigger>
    <primitives:menu.contextTrigger />
    <primitives:menu.positioner>
        <primitives:menu.arrow />
        <primitives:menu.content>
            <primitives:menu.item>
                <primitives:menu.itemText />
            </primitives:menu.item>
            <primitives:menu.checkboxItem>
                <primitives:menu.itemIndicator />
                <primitives:menu.itemText />
            </primitives:menu.checkboxItem>
            <primitives:menu.radioItem>
                <primitives:menu.itemIndicator />
                <primitives:menu.itemText />
            </primitives:menu.radioItem>
            <primitives:menu.separator />
            <primitives:menu.itemGroup>
                <primitives:menu.itemGroupLabel />
            </primitives:menu.itemGroup>

            <f:comment><!-- Opens the submenu below, matched by rootId/childId --></f:comment>
            <primitives:menu.triggerItem childId="submenu" />
        </primitives:menu.content>
    </primitives:menu.positioner>
</primitives:menu.root>

<f:comment><!-- A submenu: linked to its parent by id --></f:comment>
<primitives:menu.root rootId="submenu" parentId="parent-rootId">
    <primitives:menu.positioner>
        <primitives:menu.content>
            <primitives:menu.item />
        </primitives:menu.content>
    </primitives:menu.positioner>
</primitives:menu.root>

        

Installation

typo3 ui:add menu

Read more about installing Components and Primitives.

Examples

Wrap related items in a menu.itemGroup and name it with a menu.itemGroupLabel. A menu.separator divides the groups.

<ui:menu.root>
    <ui:menu.trigger>File</ui:menu.trigger>
    <ui:menu.content>
        <ui:menu.itemGroup value="file-group">
            <ui:menu.itemGroupLabel>File</ui:menu.itemGroupLabel>
            <ui:menu.item value="new">New</ui:menu.item>
            <ui:menu.item value="open">Open</ui:menu.item>
            <ui:menu.item value="save">Save</ui:menu.item>
        </ui:menu.itemGroup>
        <ui:menu.separator />
        <ui:menu.itemGroup value="edit-group">
            <ui:menu.itemGroupLabel>Edit</ui:menu.itemGroupLabel>
            <ui:menu.item value="undo">Undo</ui:menu.item>
            <ui:menu.item value="redo">Redo</ui:menu.item>
        </ui:menu.itemGroup>
    </ui:menu.content>
</ui:menu.root>

Link to pages

Set asChild="{true}" on a menu.item to put its attributes on your <a href>. The item navigates like a regular link, also from the keyboard.

<ui:menu.root>
    <ui:menu.trigger>Navigate</ui:menu.trigger>
    <ui:menu.content>
        <ui:menu.item asChild="{true}" value="home">
            <a href="/">Home</a>
        </ui:menu.item>
        <ui:menu.item asChild="{true}" value="docs">
            <a href="/docs/introduction">Documentation</a>
        </ui:menu.item>
        <ui:menu.item asChild="{true}" value="github">
            <a href="https://github.com/jramke/fluid-primitives" target="_blank" rel="noreferrer">GitHub</a>
        </ui:menu.item>
    </ui:menu.content>
</ui:menu.root>

Toggle options

Use menu.checkboxItem for options that switch on and off independently. The root sets closeOnSelect="{false}", so the menu stays open while you check several.

<ui:menu.root closeOnSelect="{false}">
    <ui:menu.trigger>View</ui:menu.trigger>
    <ui:menu.content>
        <ui:menu.checkboxItem value="toolbar">Show Toolbar</ui:menu.checkboxItem>
        <ui:menu.checkboxItem value="sidebar" checked="{true}">Show Sidebar</ui:menu.checkboxItem>
        <ui:menu.checkboxItem value="statusbar">Show Status Bar</ui:menu.checkboxItem>
    </ui:menu.content>
</ui:menu.root>

Choose one option

Radio items that share a name are mutually exclusive: choosing one unchecks the others.

<ui:menu.root closeOnSelect="{false}">
    <ui:menu.trigger>Sort By</ui:menu.trigger>
    <ui:menu.content>
        <ui:menu.radioItem name="sort" value="name" checked="{true}">Name</ui:menu.radioItem>
        <ui:menu.radioItem name="sort" value="date">Date Modified</ui:menu.radioItem>
        <ui:menu.radioItem name="sort" value="size">Size</ui:menu.radioItem>
    </ui:menu.content>
</ui:menu.root>

Add a submenu

Link a submenu to its parent by id: give its menu.root a rootId and a parentId that is the parent's rootId, then add a menu.triggerItem with a matching childId to the parent's content. Open Share or Export below.

<ui:menu.root rootId="file-menu">
    <ui:menu.trigger>File</ui:menu.trigger>
    <ui:menu.content>
        <ui:menu.item value="new-tab">New Tab</ui:menu.item>
        <ui:menu.item value="new-window">New Window</ui:menu.item>
        <ui:menu.separator />
        <ui:menu.triggerItem childId="share-menu">Share</ui:menu.triggerItem>
        <ui:menu.triggerItem childId="export-menu">Export</ui:menu.triggerItem>
        <ui:menu.separator />
        <ui:menu.item value="print">Print…</ui:menu.item>
    </ui:menu.content>
</ui:menu.root>

<ui:menu.root rootId="share-menu" parentId="file-menu" positioning="{ placement: 'right-start' }">
    <ui:menu.content>
        <ui:menu.item value="email">Email</ui:menu.item>
        <ui:menu.item value="messages">Messages</ui:menu.item>
        <ui:menu.item value="airdrop">AirDrop</ui:menu.item>
    </ui:menu.content>
</ui:menu.root>

<ui:menu.root rootId="export-menu" parentId="file-menu" positioning="{ placement: 'right-start' }">
    <ui:menu.content>
        <ui:menu.item value="pdf">PDF</ui:menu.item>
        <ui:menu.item value="png">PNG</ui:menu.item>
        <ui:menu.item value="svg">SVG</ui:menu.item>
    </ui:menu.content>
</ui:menu.root>

Open on right-click

Wrap an area in a menu.contextTrigger to open the menu on right-click. Add a regular menu.trigger as well to open the same menu from a button.

Right-click this area

<ui:menu.root>
    <ui:menu.contextTrigger>
        Right-click this area
    </ui:menu.contextTrigger>
    <ui:menu.content>
        <ui:menu.item value="cut">Cut</ui:menu.item>
        <ui:menu.item value="copy">Copy</ui:menu.item>
        <ui:menu.item value="paste">Paste</ui:menu.item>
    </ui:menu.content>
</ui:menu.root>

Give each menu.trigger its own value and they open the same menu. onTriggerValueChange tells you which one opened it, so an item can act on what its trigger belongs to.

<ui:menu.root autoMount="{false}" rootId="menu-multiple-triggers">
    <div class="flex gap-2">
        <ui:menu.trigger value="A">Trigger A</ui:menu.trigger>
        <ui:menu.trigger value="B">Trigger B</ui:menu.trigger>
    </div>
    <ui:menu.content>
        <ui:menu.item value="edit">Edit</ui:menu.item>
        <ui:menu.item value="duplicate">Duplicate</ui:menu.item>
        <ui:menu.item value="delete">Delete</ui:menu.item>
    </ui:menu.content>
</ui:menu.root>

<vite:asset entry="EXT:docs/Resources/Private/Components/ui/MenuExamples/MultipleTriggers.entry.ts" />

import { mount } from 'fluid-primitives';
import { Menu } from 'fluid-primitives/menu';

mount('ui:menu', 'menu-multiple-triggers', ({ props }) => {
    let trigger: string | null = null;

    return new Menu({
        ...props,
        onTriggerValueChange: ({ value }) => (trigger = value),
        onSelect: ({ value }) => alert(`Clicked ${value} of trigger ${trigger}`),
    }).init();
});

Detached triggers

The trigger sits apart from the menu and links to a menu.provider with provider, a contextTrigger takes it too. The provider takes the props of the menu: here positioning, which aligns the menu to the end of the trigger. Its id is the rootId of the menu, so a submenu names it in parentId. See Providers.

Meeting notes

<ui:menu.provider id="note-actions" positioning="{ placement: 'bottom-end' }" />

<div class="flex items-center justify-between gap-4">
    <span>Meeting notes</span>
    <ui:menu.trigger provider="note-actions">Actions</ui:menu.trigger>
</div>

<ui:menu.root provider="note-actions">
    <ui:menu.content>
        <ui:menu.item value="rename">Rename</ui:menu.item>
        <ui:menu.triggerItem childId="note-share">Share</ui:menu.triggerItem>
        <ui:menu.separator />
        <ui:menu.item value="delete">Delete</ui:menu.item>
    </ui:menu.content>
</ui:menu.root>

<f:comment>The id of the provider is the rootId of the menu, so parentId names it.</f:comment>
<ui:menu.root rootId="note-share" parentId="note-actions" positioning="{ placement: 'right-start' }">
    <ui:menu.content>
        <ui:menu.item value="email">Email</ui:menu.item>
        <ui:menu.item value="copy-link">Copy link</ui:menu.item>
    </ui:menu.content>
</ui:menu.root>

Menus portal to the end of the <body>. Set portalled="{false}" on menu.content inside a dialog, or another focus-trapped element, to keep the menu in its DOM subtree.

<ui:dialog.root>
    <ui:dialog.trigger asChild="{true}">
        <ui:button>Open Dialog</ui:button>
    </ui:dialog.trigger>
    <ui:dialog.content>
        <ui:dialog.header>
            <ui:dialog.title>Project Settings</ui:dialog.title>
            <ui:dialog.description>
                The menu below sets <code>portalled="{false}"</code> on <code>ui:menu.content</code> so it
                stays inside this dialog's DOM subtree instead of portalling to the document body.
            </ui:dialog.description>
        </ui:dialog.header>
        <ui:menu.root>
            <ui:menu.trigger class="self-start">Options</ui:menu.trigger>
            <ui:menu.content portalled="{false}">
                <ui:menu.item value="rename">Rename</ui:menu.item>
                <ui:menu.item value="duplicate">Duplicate</ui:menu.item>
                <ui:menu.item value="archive">Archive</ui:menu.item>
            </ui:menu.content>
        </ui:menu.root>
        <ui:dialog.footer>
            <ui:dialog.close asChild="{true}">
                <ui:button variant="secondary">Close</ui:button>
            </ui:dialog.close>
        </ui:dialog.footer>
    </ui:dialog.content>
</ui:dialog.root>

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

menu.root

Provides shared menu state to the rest of the parts. Renders no element of its own.

Name	Description	Required	Default
`closeOnSelect`	`boolean` Whether to close the menu when an option is selected.	No	true
`composite`	`boolean` Whether the menu is composed with other composite widgets like a combobox or tabs.	No	true
`typeahead`	`boolean` Whether pressing printable characters should trigger typeahead navigation.	No	true
`loopFocus`	`boolean` Whether to loop the keyboard navigation.	No	false
`positioning`	`array` The options used to dynamically position the menu.	No	{ "placement": "bottom-start", "gutter": 8 }
`defaultOpen`	`boolean` The initial open state of the menu when rendered. Use when you don't need to control the open state of the menu.	No	false
`defaultHighlightedValue`	`string` The initial highlighted value of the menu item when rendered.	No	-
`defaultTriggerValue`	`string` The initial trigger value when rendered, for a menu with multiple triggers.	No	-
`ariaLabel`	`string` The accessibility label for the menu. Forwarded to the machine as `aria-label`.	No	-
`parentId`	`string` The `rootId` of the parent menu this menu is a submenu of. Must match a `menu.triggerItem`'s `childId` on that parent, pointing back at this menu's own `rootId` - see the Nested Menu docs example.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true
`provider`	`string` The `id` of the `.provider` this root takes its `rootId` and props from.	No	-

menu.trigger

Opens and closes the menu. Renders a <button> element.

Name	Description	Required	Default
`provider`	`string` The `id` of the `<component>.provider` this part belongs to, when it renders outside its root.	No	-
`value`	`string` The value that identifies this specific trigger, for a menu with multiple triggers.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-menu-trigger`	<uid>
`data-disabled`	Present when disabled
`data-placement`	The placement of the trigger
`data-side`	The side of the trigger that the trigger is positioned on
`data-value`	The value of the item
`data-current`	Present when current
`data-controls`
`data-state`	"open" \| "closed"

menu.contextTrigger

Opens the menu at the cursor position on right-click. Renders a <div> element.

Name	Description	Required	Default
`provider`	`string` The `id` of the `<component>.provider` this part belongs to, when it renders outside its root.	No	-
`value`	`string` The value that identifies this specific context trigger, for a menu with multiple context triggers.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-menu-context-trigger`	<uid>
`data-value`	The value of the item
`data-current`	Present when current
`data-state`	"open" \| "closed"

menu.content

Contains the menu items. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-menu-content`	<uid>
`data-state`	"open" \| "closed"
`data-instant`
`data-placement`	The placement of the content
`data-side`	The side of the trigger that the content is positioned on
`data-nested`	menu
`data-has-nested`	menu

menu.item

A selectable menu action. Renders a <div> element.

Name	Description	Required	Default
`value`	`string` The unique value of the menu item.	Yes	-
`disabled`	`boolean` Whether the menu item is disabled.	No	-
`valueText`	`string` The textual value of the item, used for typeahead navigation. Falls back to the item's text content when omitted.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-menu-item`	<uid>
`data-disabled`	Present when disabled
`data-highlighted`	Present when highlighted
`data-value`	The value of the item
`data-valuetext`	The human-readable value

menu.checkboxItem

A menu item that toggles independently of other items. Renders a <div> element.

Name	Description	Required	Default
`value`	`string` The unique value of the checkbox item.	Yes	-
`checked`	`boolean` Whether the checkbox item is checked when rendered.	No	false
`disabled`	`boolean` Whether the checkbox item is disabled.	No	-
`valueText`	`string` The textual value of the item, used for typeahead navigation. Falls back to the item's text content when omitted.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

menu.radioItem

A menu item that's mutually exclusive with other radio items sharing the same name. Renders a <div> element.

Name	Description	Required	Default
`value`	`string` The unique value of the radio item.	Yes	-
`checked`	`boolean` Whether the radio item is checked when rendered.	No	false
`disabled`	`boolean` Whether the radio item is disabled.	No	-
`valueText`	`string` The textual value of the item, used for typeahead navigation. Falls back to the item's text content when omitted.	No	-
`name`	`string` Groups radio items so selecting one unchecks the others sharing the same `name`.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

menu.itemGroup

Groups related items together. Renders a <div> element.

Name	Description	Required	Default
`value`	`string` The value identifier of the item group. Picked up automatically by a `menu.itemGroupLabel` nested inside it.	Yes	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

menu.itemGroupLabel

Labels an itemGroup. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

menu.separator

A visual divider between items. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

menu.triggerItem

Opens a nested submenu from within another menu's content. Renders a <div> element.

Name	Description	Required	Default
`childId`	`string` The `rootId` of the submenu (its `menu.root`'s `rootId`) that this item opens. That submenu's own `parentId` must point back at this menu's `rootId`.	Yes	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Machine JavaScript API

Name	Type	Description
`open`	`boolean`	Whether the menu is open
`setOpen`	`(open: boolean) => void`	Function to open or close the menu
`triggerValue`	`string \| null`	The trigger value
`setTriggerValue`	`(value: string \| null) => void`	Function to set the trigger value
`highlightedValue`	`string \| null`	The id of the currently highlighted menuitem
`setHighlightedValue`	`(value: string) => void`	Function to set the highlighted menuitem
`setParent`	`(parent: MenuService) => void`	Function to register a parent menu. This is used for submenus
`setChild`	`(child: MenuService) => void`	Function to register a child menu. This is used for submenus
`reposition`	`(options?: Partial<PositioningOptions>) => void`	Function to reposition the popover
`getOptionItemState`	`(props: OptionItemProps) => OptionItemState`	Returns the state of the option item
`getItemState`	`(props: ItemProps) => ItemState`	Returns the state of the menu item
`addItemListener`	`(props: ItemListenerProps) => VoidFunction \| undefined`	Setup the custom event listener for item selection event
`getTriggerState`	`(props?: TriggerProps) => TriggerState`	Returns the state of a specific trigger, including whether it's the currently active one
`getPositionerState`	`() => PositionerState`	Returns the state of the positioner
`getContentState`	`() => ContentState`	Returns the state of the content

Accessibility

Key	Description
`Space`	Activates/Selects the highlighted item
`Enter`	Activates/Selects the highlighted item
`ArrowDown`	Highlights the next item in the menu
`ArrowUp`	Highlights the previous item in the menu
`ArrowRightArrowLeft`	When focus is on trigger, opens or closes the submenu depending on reading direction.
`Esc`	Closes the menu and moves focus to the trigger

Menu

Features

Anatomy

Installation

Examples

Group related items

Link to pages

Toggle options

Choose one option

Add a submenu

Open on right-click

Share one menu between triggers

Detached triggers

Use a menu inside a dialog

API Reference

menu.root

menu.trigger

Rendered data attributes

menu.contextTrigger

Rendered data attributes

menu.content

Rendered data attributes

menu.item

Rendered data attributes

menu.checkboxItem

menu.radioItem

menu.itemGroup

menu.itemGroupLabel

menu.separator

menu.triggerItem

Machine JavaScript API

Accessibility