MenuItem

MenuItem represents individual clickable items within dropdown menus and other menu components. Each menu item can display text, icons, and respond to clicks with either navigation or custom actions, making it the building block for interactive menu systems.

Key features:

• Action handling: Support both navigation (to property) and custom click handlers
• Visual feedback: Built-in active, hover, and disabled states for clear user interaction
• Icon support: Optional icons with flexible positioning (start or end)
• Menu integration: Designed to work seamlessly within DropdownMenu and SubMenuItem hierarchies

Usage pattern: Always used within menu containers like DropdownMenu. Use to for navigation or onClick for custom actions. For complex menu structures, combine with MenuSeparator and SubMenuItem components.

Behaviors

This component supports the following behaviors:

Properties

active

default: false

This property indicates if the specified menu item is active.

<App>
  <DropdownMenu label="DropdownMenu">
    <MenuItem icon="drive" active="true">Item 1</MenuItem>
    <MenuItem icon="trash">Item 2</MenuItem>
    <MenuItem icon="email">Item 3</MenuItem>
  </DropdownMenu>
</App>

<App>
  <DropdownMenu label="DropdownMenu">
    <MenuItem icon="drive" active="true">Item 1</MenuItem>
    <MenuItem icon="trash">Item 2</MenuItem>
    <MenuItem icon="email">Item 3</MenuItem>
  </DropdownMenu>
</App>

enabled

default: true

This boolean property value indicates whether the component responds to user events (true) or not (false).

icon

This property names an optional icon to display with the menu item. You can use component-specific icons in the format "iconName:MenuItem".

<App>
  <DropdownMenu label="DropdownMenu">
    <MenuItem icon="drive">Item 1</MenuItem>
    <MenuItem icon="trash">Item 2</MenuItem>
    <MenuItem icon="email">Item 3</MenuItem>
  </DropdownMenu>
</App>

<App>
  <DropdownMenu label="DropdownMenu">
    <MenuItem icon="drive">Item 1</MenuItem>
    <MenuItem icon="trash">Item 2</MenuItem>
    <MenuItem icon="email">Item 3</MenuItem>
  </DropdownMenu>
</App>

iconPosition

default: "start"

This property allows you to determine the position of the icon displayed in the menu item.

Available values:

<App>
  <DropdownMenu label="DropdownMenu">
    <MenuItem icon="drive" iconPosition="start">Item 1</MenuItem>
    <MenuItem icon="trash" iconPosition="end">Item 2</MenuItem>
    <MenuItem icon="email">Item 3</MenuItem>
  </DropdownMenu>
</App>

<App>
  <DropdownMenu label="DropdownMenu">
    <MenuItem icon="drive" iconPosition="start">Item 1</MenuItem>
    <MenuItem icon="trash" iconPosition="end">Item 2</MenuItem>
    <MenuItem icon="email">Item 3</MenuItem>
  </DropdownMenu>
</App>

label

This property sets the label of the component. If not set, the component will not display a label.

target

This property specifies where to open the link represented by the MenuItem. It only has an effect when to is defined. This property accepts the following values (in accordance with the HTML standard):

Available values:

This property only has an effect when to is set.

<App>
  <DropdownMenu label="DropdownMenu">
    <MenuItem to="https://github.com/xmlui-org/xmlui" target="_blank">
      Open GitHub in a new tab
    </MenuItem>
  </DropdownMenu>
</App>

<App>
  <DropdownMenu label="DropdownMenu">
    <MenuItem to="https://github.com/xmlui-org/xmlui" target="_blank">
      Open GitHub in a new tab
    </MenuItem>
  </DropdownMenu>
</App>

to

This property defines the URL of the menu item. When it is set, the menu item renders as a real link (an <a> element with an href), so it can be opened in a new tab, copied, and read as a link by assistive technology. If this property is defined (and the click event does not have an event handler), clicking the menu item navigates to this link.

When to is set, the menu item is rendered as a real link — an <a> element with an href — rather than as an element that merely reacts to a click. That means the browser's own link affordances work: ctrl/cmd-click and middle-click open the target in a new tab, the target shows in the status bar on hover, "Copy link address" works from the browser context menu, and assistive technology can report the destination.

<App>
  <DropdownMenu label="Navigate">
    <MenuItem to="/getting-started">Getting started</MenuItem>
    <MenuItem to="/reference">Reference</MenuItem>
    <MenuItem to="https://github.com/xmlui-org/xmlui">GitHub</MenuItem>
  </DropdownMenu>
</App>

<App>
  <DropdownMenu label="Navigate">
    <MenuItem to="/getting-started">Getting started</MenuItem>
    <MenuItem to="/reference">Reference</MenuItem>
    <MenuItem to="https://github.com/xmlui-org/xmlui">GitHub</MenuItem>
  </DropdownMenu>
</App>

Do not put another link or button (Link, NavLink, Button) inside a MenuItem that declares to. Because the menu item is itself a link, nesting one produces invalid markup that browsers and assistive technology handle unpredictably. Either drop to from the menu item or remove the nested component.

Events

click

This event is triggered when the MenuItem is clicked.

Signature: click(event: MouseEvent): void

• event: The mouse event object.

This event is fired when the user clicks the menu item. With an event handler, you can define how to respond to the user's click. If this event does not have an associated event handler but the to property has a value, clicking the component navigates the URL set in to.

If both properties are defined, click takes precedence: a plain click runs the event handler and does not navigate. The href is still rendered, so the user can deliberately open the target — for example with ctrl/cmd-click — in which case the browser follows the link and the event handler does not run.

<DropdownMenu label="DropdownMenu">
  <MenuItem onClick="toast('Item 1 clicked')">Item 1</MenuItem>
  <MenuItem onClick="toast('Item 2 clicked')">Item 2</MenuItem>
  <MenuItem onClick="toast('Item 3 clicked')">Item 3</MenuItem>
</DropdownMenu>

<DropdownMenu label="DropdownMenu">
  <MenuItem onClick="toast('Item 1 clicked')">Item 1</MenuItem>
  <MenuItem onClick="toast('Item 2 clicked')">Item 2</MenuItem>
  <MenuItem onClick="toast('Item 3 clicked')">Item 3</MenuItem>
</DropdownMenu>

Exposed Methods

This component does not expose any methods.

Styling

Theme Variables