Menu
A dropdown menu: a list of actions in a panel anchored to a trigger. Render Menu.Trigger and Menu.Content inside it.
Arrow keys, Home, End, and typing move through the items, and Escape closes it.
Built on bits-ui DropdownMenu.
<Menu bind:open> <Menu.Trigger class="button">Actions</Menu.Trigger> <Menu.Content> <Menu.Item onclick={rename}> <Icon icon={mdiPencil} size="sm" /> Rename </Menu.Item> <Menu.Item variant="danger" onclick={remove}>Delete</Menu.Item> </Menu.Content></Menu>- Composed from parts, so the trigger, the items, and the separators are yours to arrange.
openis bindable, two-way or as a getter and setter. State & binding explains both modes.- Item activation is the native
onclick, which fires for a click, Enter, and Space. The menu closes after an item is activated. - Checkbox and radio items are bind-only:
bind:checkedandbind:value, with no change callback. - The menu floats in a portal, positioned to the trigger, and flips to the other side when there is no room.
- Typing characters focuses the item whose text starts with them.
- Escape closes the menu and returns focus to the trigger.
Anatomy
Section titled “Anatomy”Every part is a property on Menu. Menu renders no element. Menu.Content portals itself to the body.
<Menu> <Menu.Trigger /> <Menu.Content> <Menu.Item /> <Menu.CheckboxItem /> <Menu.RadioGroup> <Menu.RadioItem /> </Menu.RadioGroup> <Menu.Separator /> <Menu.Group> <Menu.GroupHeading /> <Menu.Item> <Menu.Shortcut /> </Menu.Item> </Menu.Group> <Menu.Sub> <Menu.SubTrigger /> <Menu.SubContent /> </Menu.Sub> </Menu.Content></Menu>Two-way binding
Section titled “Two-way binding”bind:open on the root.
open: false
Code
<script lang="ts"> import { Menu } from "@viamrobotics/prime-ui";
let open = $state(false);</script>
<div class="not-content"> <Menu bind:open> <Menu.Trigger class="button">Actions</Menu.Trigger> <Menu.Content> <Menu.Item>Rename</Menu.Item> <Menu.Item>Duplicate</Menu.Item> </Menu.Content> </Menu>
<p class="mt-3 text-sm text-subtle-2">open: <code>{open}</code></p></div>Fully controlled
Section titled “Fully controlled”Pass bind:open a getter and a setter. The setter can decline a change.
Code
<script lang="ts"> import { Menu } from "@viamrobotics/prime-ui";
let open = $state(false); let isLocked = $state(true);</script>
<div class="not-content flex flex-col items-start gap-3"> <label class="flex items-center gap-2 text-sm"> <input type="checkbox" bind:checked={isLocked} /> Keep closed </label>
<Menu bind:open={ () => open, (next) => { if (!isLocked) open = next; } } > <Menu.Trigger class="button">Actions</Menu.Trigger> <Menu.Content> <Menu.Item>Rename</Menu.Item> <Menu.Item>Duplicate</Menu.Item> </Menu.Content> </Menu></div>Checkbox and radio items
Section titled “Checkbox and radio items”Menu.CheckboxItem takes bind:checked. Menu.RadioGroup takes bind:value, and each Menu.RadioItem has the value it selects.
grid: true, sort: name
Code
<script lang="ts"> import { Menu } from "@viamrobotics/prime-ui";
let isGridShown = $state(true); let sort = $state("name");</script>
<div class="not-content"> <Menu> <Menu.Trigger class="button">View</Menu.Trigger> <Menu.Content> <Menu.CheckboxItem bind:checked={isGridShown}>Show grid</Menu.CheckboxItem> <Menu.Separator /> <Menu.RadioGroup bind:value={sort}> <Menu.GroupHeading>Sort by</Menu.GroupHeading> <Menu.RadioItem value="name">Name</Menu.RadioItem> <Menu.RadioItem value="date">Date</Menu.RadioItem> <Menu.RadioItem value="size">Size</Menu.RadioItem> </Menu.RadioGroup> </Menu.Content> </Menu>
<p class="mt-3 text-sm text-subtle-2"> grid: <code>{isGridShown}</code>, sort: <code>{sort}</code> </p></div>Submenus
Section titled “Submenus”Menu.Sub holds a Menu.SubTrigger and a Menu.SubContent. ArrowRight opens it and ArrowLeft closes it.
Code
<script lang="ts"> import { Menu } from "@viamrobotics/prime-ui";</script>
<div class="not-content"> <Menu> <Menu.Trigger class="button">File</Menu.Trigger> <Menu.Content> <Menu.Item>Open</Menu.Item> <Menu.Sub> <Menu.SubTrigger>Export as</Menu.SubTrigger> <Menu.SubContent> <Menu.Item>PNG</Menu.Item> <Menu.Item>SVG</Menu.Item> <Menu.Item>PDF</Menu.Item> </Menu.SubContent> </Menu.Sub> </Menu.Content> </Menu></div>Placement
Section titled “Placement”Menu.Content takes side and align to place the menu, and sideOffset and alignOffset to nudge it.
Code
<script lang="ts"> import { Menu } from "@viamrobotics/prime-ui";</script>
<div class="not-content pt-32"> <Menu> <Menu.Trigger class="button">Open above</Menu.Trigger> <Menu.Content side="top" align="end" sideOffset={8}> <Menu.Item>Rename</Menu.Item> <Menu.Item>Duplicate</Menu.Item> </Menu.Content> </Menu></div>Item kinds
Section titled “Item kinds”Iconed item
Item with shortcut
The shortcut is hidden from assistive technology, so the item is announced as "Save" alone.
Checkbox item
Radio group
Submenu
Separator and group heading
Danger item
Disabled item
Shortcuts
Section titled “Shortcuts”Menu.Shortcut is a hint and nothing more. It is decorative and hidden from assistive technology, so an item’s accessible name is its text alone. Binding the key is the app’s job.
Styling
Section titled “Styling”Every part that renders an element takes class on that element. Menu.Trigger is a real <button> with no look of its own beyond the focus ring, so add button or button-ghost. Menu and Menu.Sub render no element, so they take no class. bits-ui sets the data attributes below. Menu.Content wears z-menu; see z layers.
| Part | Attribute | Value |
|---|---|---|
Trigger |
data-state |
open or closed |
Content |
data-state |
open or closed |
Content |
data-side |
the resolved side of the trigger |
Content |
data-align |
the resolved alignment |
SubTrigger |
data-state |
open or closed |
SubContent |
data-state |
open or closed |
Item |
data-highlighted |
present while focused or hovered |
Item |
data-disabled |
present when disabled |
Item |
data-variant |
default or danger |
Keyboard
Section titled “Keyboard”| Key | Action |
|---|---|
| Enter / Space / ArrowDown | On the trigger, opens the menu. |
| ArrowDown / ArrowUp | Moves focus to the next or previous item. |
| Home / End | Moves focus to the first or last item. |
| ArrowRight / ArrowLeft | Opens a submenu, or closes it and returns to its parent. |
| Typed characters | Focuses the next item whose text starts with them. |
| Enter / Space | On an item, activates it and closes the menu. |
| Escape | Closes the menu and focuses the trigger. |
| Prop | Type | Default | Description |
|---|---|---|---|
bind:open | boolean | Whether the menu is open. Two-way bindable. | |
children | Snippet | The Menu.* parts. |
Menu.CheckboxItem
A toggle in a Menu.Content. Bind checked two-way, or as a getter and setter to
veto or transform a change. A check icon leads the label while checked. The menu closes after a toggle.
<Menu.CheckboxItem bind:checked={showHidden}>Show hidden</Menu.CheckboxItem>| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
bind:checked | boolean | false | Checked state. Two-way bindable. |
disabled | boolean | false | Prevent the item from being toggled. |
children | Snippet<[{ checked: boolean }]> | The item's content. Receives { checked }. |
Plus everything in Omit<HTMLAttributes<HTMLDivElement>, 'children'>, spread onto the element.
Menu.Content
The floating panel of a Menu, portaled to the body. It holds Menu.Item parts and the other menu parts.
It closes on Escape and on a press outside, and returns focus to the trigger.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
dir | 'ltr' | 'rtl' | Text direction of the panel. auto is not accepted, because positioning needs a concrete direction. | |
side | 'top' | 'right' | 'bottom' | 'left' | 'bottom' | Which side of the trigger the panel opens on. |
align | 'start' | 'center' | 'end' | 'start' | Alignment of the panel along the trigger's edge. |
sideOffset | number | 4 | Gap in pixels between the trigger and the panel. |
alignOffset | number | 0 | Shift in pixels along the alignment axis. |
portal | PortalTarget | true | Where the panel renders: true at the end of <body>, false in place, or inside an element or the first match of a CSS selector. |
Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.
Menu.Group
A set of related items in a Menu.Content, labeled by its Menu.GroupHeading.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. |
Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.
Menu.GroupHeading
A non-interactive heading that labels the Menu.Group or
Menu.RadioGroup it sits in. It must be a child of one of those, and
rendering it directly in the content throws when the menu opens.
Takes extraClasses, children, ...restProps }: Props as its props.
Menu.Item
An action in a Menu.Content. Activation is the native onclick, which fires for a click, Enter, and Space.
The menu closes after the item is activated. A leading icon is part of the children.
<Menu.Item onclick={rename}> <Icon icon={mdiPencil} size="sm" /> Rename</Menu.Item>| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
variant | 'default' | 'danger' | 'default' | Visual treatment. danger marks a destructive action. |
disabled | boolean | false | Prevent the item from being activated. |
Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.
Menu.RadioGroup
A set of Menu.RadioItems sharing one value. Bind value two-way, or as a getter
and setter to veto or transform a change.
<Menu.RadioGroup bind:value={size}> <Menu.RadioItem value="small">Small</Menu.RadioItem> <Menu.RadioItem value="large">Large</Menu.RadioItem></Menu.RadioGroup>| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
bind:value | string | The selected Menu.RadioItem's value. Two-way bindable. |
Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.
Menu.RadioItem
A choice in a Menu.RadioGroup. Selecting it sets the group’s value to this item’s
value. A check icon leads the label while selected. The menu closes after a selection.
<Menu.RadioItem value="small">Small</Menu.RadioItem>Takes extraClasses, children: content, ...restProps }: Props as its props.
Menu.Separator
A horizontal rule between groups of items in a Menu.Content.
Takes extraClasses, children, ...restProps }: Props as its props.
Menu.Shortcut
A keyboard shortcut hint at the end of a Menu.Item. It is decorative and hidden from
assistive technology, so the item’s accessible name is its text alone. Binding the key is the app’s job.
<Menu.Item onclick={save}> Save <Menu.Shortcut>⌘S</Menu.Shortcut></Menu.Item>Takes extraClasses, children, ...restProps }: Props as its props.
Menu.Sub
A nested menu inside a Menu.Content. It holds one Menu.SubTrigger and one Menu.SubContent.
<Menu.Sub bind:open> <Menu.SubTrigger>Export</Menu.SubTrigger> <Menu.SubContent> <Menu.Item onclick={exportPdf}>PDF</Menu.Item> </Menu.SubContent></Menu.Sub>| Prop | Type | Default | Description |
|---|---|---|---|
bind:open | boolean | Whether the submenu is open. Two-way bindable. | |
children | Snippet | A Menu.SubTrigger and a Menu.SubContent. |
Menu.SubContent
The floating panel of a Menu.Sub. It opens beside its Menu.SubTrigger, closes on ArrowLeft, and returns focus to the trigger.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
dir | 'ltr' | 'rtl' | Text direction of the panel. auto is not accepted, because positioning needs a concrete direction. | |
sideOffset | number | 4 | Gap in pixels between the trigger and the panel. |
alignOffset | number | -4 | Shift in pixels along the trigger's edge, so the first item lines up with the trigger. |
Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.
Menu.SubTrigger
The item in a Menu.Content that opens a Menu.Sub. It opens on hover, Enter, Space, and ArrowRight.
A trailing chevron marks it as a submenu.
Takes extraClasses, children, ...restProps }: Props as its props.
Menu.Trigger
The button that toggles a Menu. It renders a real <button>, so button or button-ghost styles it.
Arrow Down on the focused trigger opens the menu and focuses the first item.
Takes extraClasses, children, ...restProps }: Props as its props.