UI Ingredients v1.6.0
Github

Menu

A component for navigating through a list of options or actions

Anatomy

Usage

Basic Menu

<script>
  import {Menu} from 'ui-ingredients';
  import {CheckIcon, ChevronDownIcon} from '$lib/icons';

  let items = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5'];
</script>

<Menu.Root>
  <Menu.Trigger>
    Trigger
    <Menu.Indicator>
      <ChevronDownIcon />
    </Menu.Indicator>
  </Menu.Trigger>
  <Menu.Positioner>
    <Menu.Content>
      {#each items as item}
        <Menu.Item value={item}>
          {item.value}
        </Menu.Item>
      {/each}
    </Menu.Content>
  </Menu.Positioner>
</Menu.Root>

Radio/Checkbox Menu

<script>
  import {Menu} from 'ui-ingredients';
  import {CheckIcon, ChevronDownIcon} from '$lib/icons';

  let items = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5'];

  /** @type {string[]} */
  let selected = $state([]);
</script>

<Menu.Root>
  <Menu.Trigger>
    Trigger
    <Menu.Indicator>
      <ChevronDownIcon />
    </Menu.Indicator>
  </Menu.Trigger>
  <Menu.Positioner>
    <Menu.Content>
      {#each items as item (item)}
        <Menu.OptionItem
          type="checkbox"
          value={item}
          valueText={item}
          closeOnSelect={false}
          checked={selected.includes(item)}
          onCheckedChange={function (checked) {
            selected = checked
              ? [...selected, item]
              : [...selected].filter(function (value) {
                  return value !== item;
                });
          }}
        >
          <Menu.OptionItemIndicator>
            <CheckIcon />
          </Menu.OptionItemIndicator>
          <Menu.OptionItemText />
        </Menu.OptionItem>
      {/each}
    </Menu.Content>
  </Menu.Positioner>
</Menu.Root>

Nested Menu

<script>
  import {Menu} from 'ui-ingredients';
  import {ChevronRightIcon} from '$lib/icons';
</script>

<Menu.Root>
  <Menu.Trigger>
    Trigger
    <Menu.Indicator>
      <ChevronDownIcon />
    </Menu.Indicator>
  </Menu.Trigger>
  <Menu.Positioner>
    <Menu.Content>
      <Menu.Item value="1">Item 1</Menu.Item>
      <Menu.Item value="2">Item 2</Menu.Item>
      <Menu.Root
        positioning={{
          placement: 'right',
        }}
      >
        <Menu.TriggerItem>
          Nested Trigger
          <ChevronRightIcon />
        </Menu.TriggerItem>
        <Menu.Positioner>
          <Menu.Content>
            <Menu.Item value="3">Item 3</Menu.Item>
            <Menu.Item value="4">Item 4</Menu.Item>
            <Menu.Item value="5">Item 5</Menu.Item>
          </Menu.Content>
        </Menu.Positioner>
      </Menu.Root>
    </Menu.Content>
  </Menu.Positioner>
</Menu.Root>

Context Menu

<script>
  import {Menu} from 'ui-ingredients';

  let items = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5'];
</script>

<Menu.Root>
  <Menu.ContextTrigger>Trigger</Menu.ContextTrigger>
  <Menu.Positioner>
    <Menu.Content>
      {#each items as item}
        <Menu.Item value={item}>
          {item}
        </Menu.Item>
      {/each}
    </Menu.Content>
  </Menu.Positioner>
</Menu.Root>

API Reference

Root

Prop Default Description
anchorPoint Point The positioning point for the menu. Can be set by the context menu trigger or the button trigger.
aria-label string The accessibility label for the menu
closeOnSelect true boolean Whether to close the menu when an option is selected
composite true boolean Whether the menu is a composed with other composite widgets like a combobox or tabs
defaultHighlightedValue string The initial highlighted value of the menu item when rendered. Use when you don't need to control the highlighted value of the menu item.
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.
highlightedValue string The controlled highlighted value of the menu item.
id string The unique identifier of the machine.
ids { trigger?: string; contextTrigger?: string; content?: string; groupLabel(id: string)?: string; group(id: string)?: string; positioner?: string; arrow?: string; } The ids of the elements in the menu. Useful for composition.
loopFocus false boolean Whether to loop the keyboard navigation.
navigate (details: NavigateDetails) => void Function to navigate to the selected item if it's an anchor element
onEscapeKeyDown (event: KeyboardEvent) => void Function called when the escape key is pressed
onFocusOutside (event: FocusOutsideEvent) => void Function called when the focus is moved outside the component
onHighlightChange (details: HighlightChangeDetails) => void Function called when the highlighted menu item changes.
onInteractOutside (event: InteractOutsideEvent) => void Function called when an interaction happens outside the component
onOpenChange (details: OpenChangeDetails) => void Function called when the menu opens or closes
onPointerDownOutside (event: PointerDownOutsideEvent) => void Function called when the pointer is pressed down outside the component
onSelect (details: SelectionDetails) => void Function called when a menu item is selected.
open boolean The controlled open state of the menu
positioning PositioningOptions The options used to dynamically position the menu
typeahead true boolean Whether the pressing printable characters should trigger typeahead navigation

Arrow

Prop Default Description
asChild Snippet Render a different element.

ArrowTip

Prop Default Description
asChild Snippet Render a different element.

Content

Prop Default Description
asChild Snippet Render a different element.
Data Attribute Value
data-part content
data-placement The placement of the content
data-scope menu
data-state "open" | "closed"

ContextTrigger

Prop Default Description
asChild Snippet Render a different element.

Indicator

Prop Default Description
asChild Snippet Render a different element.
Data Attribute Value
data-part indicator
data-scope menu
data-state "open" | "closed"

Item

Prop Default Description
closeOnSelect boolean Whether the menu should close when the item is selected.
disabled boolean Whether the item is disabled.
value string The value of the item.
valueText string The text value of the item.
asChild Snippet Render a different element.
Data Attribute Value
data-disabled Present when disabled
data-highlighted Present when highlighted
data-part item
data-scope menu
data-value The value of the item
data-valuetext The human-readable value

ItemGroup

Prop Default Description
asChild Snippet Render a different element.

ItemGroupLabel

Prop Default Description
asChild Snippet Render a different element.

OptionItem

Prop Default Description
checked boolean Whether the item is checked.
closeOnSelect boolean Whether the menu should close when the item is selected.
disabled boolean Whether the item is disabled.
onCheckedChange (checked:boolean)=>void Callback for when the item is checked.
type 'checkbox' | 'radio' The type of the item.
value string The value of the item
valueText string The text value of the item.
Data Attribute Value
data-disabled Present when disabled
data-highlighted Present when highlighted
data-part item
data-scope menu
data-value The value of the item
data-valuetext The human-readable value

OptionItemIndicator

Prop Default Description
asChild Snippet Render a different element.
Data Attribute Value
data-disabled Present when disabled
data-highlighted Present when highlighted
data-part item-indicator
data-scope menu
data-state "checked" | "unchecked"

OptionItemText

Prop Default Description
asChild Snippet Render a different element.
Data Attribute Value
data-disabled Present when disabled
data-highlighted Present when highlighted
data-part item-text
data-scope menu
data-state "checked" | "unchecked"

Positioner

Prop Default Description
asChild Snippet Render a different element.

Separator

Prop Default Description
asChild Snippet Render a different element.

Trigger

Prop Default Description
asChild Snippet Render a different element.
Data Attribute Value
data-part trigger
data-placement The placement of the trigger
data-scope menu
data-state "open" | "closed"

TriggerItem

Prop Default Description
asChild Snippet Render a different element.

Accessibility

Keyboard Support

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
ArrowRight + ArrowLeft When focus is on trigger, opens or closes the submenu depending on reading direction.
Esc Closes the menu and moves focus to the trigger
Previous Hover Card
Next Number Input