> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/raystack/apsara/llms.txt
> Use this file to discover all available pages before exploring further.
# Menu
> A dropdown menu component with support for submenus, keyboard navigation, and optional autocomplete filtering.
## Overview
Menu provides a dropdown menu with extensive features including nested submenus, keyboard navigation, grouping, separators, and optional autocomplete filtering for large menus.
## Basic usage
```jsx theme={null}
import { Menu } from '@raystack/apsara';
```
## Components
### Menu (Root)
The root component that manages menu state and keyboard navigation.
Controls the open state of the menu (controlled mode).
The initial open state in uncontrolled mode.
Callback fired when the open state changes.
Whether the menu is modal. Always true, cannot be overridden.
Whether to loop focus when navigating with arrow keys. Always false, cannot be overridden.
Enable autocomplete mode with a search input at the top of the menu.
**Auto mode**: Automatically filters menu items based on the input value. **Manual mode**: Provides input value but doesn't filter items automatically.
Controlled value for the autocomplete input (requires `autocomplete` to be true).
Callback fired when the autocomplete input value changes.
The initial input value in uncontrolled mode.
### Menu.Trigger
A button that opens the menu when clicked.
When true, merges props with the immediate child element instead of rendering a button.
Whether to stop click event propagation.
### Menu.Content
The menu content container with positioning logic.
The preferred side of the trigger to render the menu.
The preferred alignment against the trigger.
The distance in pixels from the trigger.
Placeholder text for the autocomplete input (when `autocomplete` is enabled).
Additional CSS classes for the menu content.
### Menu.Item
An individual menu item that can be selected.
Callback fired when the item is selected.
Whether the item is disabled.
The value used for autocomplete filtering. If not provided, uses the text content.
Icon or element displayed before the item text.
Icon or element displayed after the item text.
### Menu.Group
A container for grouping related menu items.
### Menu.Label
A label for a group of menu items.
### Menu.Separator
A visual separator between menu items or groups.
### Menu.EmptyState
A component to display when no menu items match the search (useful with autocomplete).
### Menu.Submenu
A nested submenu component with its own state and autocomplete support.
Enable autocomplete mode for the submenu.
Autocomplete filtering mode for the submenu.
### Menu.SubmenuTrigger
A menu item that opens a submenu. Automatically shows a right arrow icon.
The value used for autocomplete filtering.
Icon or element displayed before the item text.
Icon or element displayed after the item text. Defaults to a right arrow.
### Menu.SubmenuContent
The content container for a submenu. Has the same props as `Menu.Content` but with `sideOffset` defaulting to `2`.
## Usage examples
### Menu with groups
```jsx theme={null}
```
### Menu with icons
```jsx theme={null}
import { PlusIcon, TrashIcon } from '@radix-ui/react-icons';
```
### Nested submenu
```jsx theme={null}
```
### Menu with autocomplete
```jsx theme={null}
```
### Controlled autocomplete
```jsx theme={null}
function ControlledMenu() {
const [search, setSearch] = useState('');
return (
);
}
```
### Submenu with autocomplete
```jsx theme={null}
```
### Disabled items
```jsx theme={null}
```
## Autocomplete filtering
The Menu component supports two autocomplete modes:
### Auto mode (default)
Automatically filters menu items based on the search input. Items that don't match are hidden:
```jsx theme={null}
```
Filtering logic:
* Matches against the `value` prop if provided
* Falls back to matching against the item's text content
* Case-insensitive matching
* Shows `Menu.EmptyState` when no items match
### Manual mode
Provides the search input but doesn't filter items automatically. You control the filtering logic:
```jsx theme={null}
function ManualFilterMenu() {
const [search, setSearch] = useState('');
const items = ['Apple', 'Banana', 'Cherry'];
const filteredItems = items.filter(item =>
item.toLowerCase().includes(search.toLowerCase())
);
return (
);
}
```
## Accessibility features
* **Keyboard navigation**: Arrow keys to navigate, Enter/Space to select
* **Type-ahead**: Start typing to highlight matching items (when autocomplete is disabled)
* **ESC to close**: Press Escape to close the menu
* **Focus management**: Automatic focus handling between menu and submenus
* **Arrow key submenu navigation**: Right arrow opens submenu, left arrow closes it
* **ARIA attributes**: Proper ARIA roles and relationships
* **Focus trap**: Focus stays within the menu when open
## Trigger patterns
The `Menu.Trigger` component can be used in two ways:
1. **Default button**: Renders a button when no children are provided or `asChild` is false
2. **Custom trigger**: Use `asChild` prop to merge menu functionality with your component
```jsx theme={null}
{/* Default button */}
Open menu
{/* Custom trigger */}
```