Unstyled Menu

The Menu components provide your users with a list of options on temporary surfaces.

Introduction

The Unstyled Menu component gives users a list of items in a popup that they can navigate through with a mouse or keyboard. It renders an unordered list (<ul>) by default.

Use the Unstyled Menu Item to add items to the menu. These are rendered as <li> elements.

Components

Usage

After installation, you can start building with this component collection using the following basic elements:

import MenuUnstyled from '@mui/base/MenuUnstyled';
import MenuItemUnstyled from '@mui/base/MenuItemUnstyled';

export default function MyApp() {
  return (
    <MenuUnstyled>
      <MenuItemUnstyled>{/* item one */}</MenuItemUnstyled>
      <MenuItemUnstyled>{/* item two */}</MenuItemUnstyled>
    </MenuUnstyled>
  );
}

Basics

The Unstyled Menu serves as a replacement for the native HTML <ul>, and the Unstyled Menu Item corresponds to the <li> tag.

The following demo shows how to create and style a Menu component. Click Dashboard to view the menu—notice that it uses the built-in Unstyled Popper component to visually break out of its parent container:

Anatomy

The Unstyled Menu component is composed of a root slot that renders an Unstyled Popper <div> by default. It contains one interior listbox <ul> slot. The Unstyled Menu Item has a single root <li> slot.

<div class="MuiMenuUnstyled-root">
  <ul class="MuiMenuUnstyled-listbox">
    <li class="MuiMenuItemUnstyled-root">List item</li>
  </ul>
</div>

Slot props

Use the component prop to override the root slot with a custom element:

<MenuItemUnstyled component="span" />

Use the slots prop to override any interior slots in addition to the root:

<MenuUnstyled slots={{ root: 'nav', listbox: 'ol' }} />

Use the slotProps prop to pass custom props to internal slots. The following code snippet applies a CSS class called my-listbox to the listbox slot:

<MenuUnstyled slotProps={{ listbox: { className: 'my-listbox' } }} />

CSS classes

Unstyled Menu can set the following class:

Mui-expanded - set when the menu is open; this class is set on both Root and Popper slots

Unstyled Menu Item can set the following classes:

Mui-disabled - set when the MenuItem has the disabled prop
Mui-focusVisible - set when the MenuItem is highlighted via keyboard navigation. This is a polyfill for the native :focus-visible pseudoclass as it's not available in Safari.

Hooks

import useMenu from '@mui/base/useMenu';
import useMenuItem from '@mui/base/useMenuItem';

The useMenu and useMenuItem hooks let you apply the functionality of the Menu components to fully custom components. They return props to be placed on the custom components, along with fields representing the components' internal states.

Hooks do not support slot props, but they do support customization props.

The following demo shows how to build a menu using hooks:

Unstyled components and their corresponding hooks work interchangeably with one another—for example, you can create an Unstyled Menu component that contains menu items built with the useMenuItem hook.

Customization

Wrapping MenuItems

Unstyled Menu Item components don't have to be direct children of a Unstyled Menu component. You can wrap them in any component needed to achieve the desired appearance.

In addition to Unstyled Menu Item components, the Unstyled Menu component can also contain non-interactive children, such as helper text.

The following demo shows an example of a menu with items grouped under non-interactive headers, along with helper text that displays the Current zoom level:

import MenuItemUnstyled from '@mui/base/MenuItemUnstyled';
// or
import { MenuItemUnstyled } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Props of the native component are also available.

Name	Type	Default	Description
component	elementType		The component used for the root node. Either a string to use a HTML element or a component.
disabled	bool	false	If `true`, the menu item will be disabled.
label	string		A text representation of the menu item's content. Used for keyboard text navigation matching.
slotProps	{ root?: func \| object }	{}	The props used for each slot inside the MenuItem.
slots	{ root?: elementType }	{}	The components used for each slot inside the MenuItem. Either a string to use a HTML element or a component. See Slots API below for more details.

The ref is forwarded to the root element.

To learn how to customize the slot, check out the Overriding component structure guide.

Name	Default class	Default HTML tag	Description
root	.MuiMenuItem-root	'li'	The component that renders the root.

You can override the style of the component using one of these customization options:

With a global class name.
With a rule name as part of the component's styleOverrides property in a custom theme.

These class names are useful for styling with CSS. They are applied to the root slot when specific states are triggered.

Global class	Description
.Mui-disabled STATE	State class applied to the root `button` element if `disabled={true}`.
.Mui-focusVisible STATE	State class applied to the root `button` element if `focusVisible={true}`.

import MenuUnstyled from '@mui/base/MenuUnstyled';
// or
import { MenuUnstyled } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Name	Type	Default	Description
actions	ref		A ref with imperative actions. It allows to select the first or last menu item.
anchorEl	HTML element \| object \| func		An HTML element, virtualElement, or a function that returns either. It's used to set the position of the popper.
component	elementType		The component used for the root node. Either a string to use a HTML element or a component.
keepMounted	bool	false	Always keep the menu in the DOM. This prop can be useful in SEO situation or when you want to maximize the responsiveness of the Menu.
onClose	func		Triggered when focus leaves the menu and the menu should close.
open	bool	false	Controls whether the menu is displayed.
slotProps	{ listbox?: func \| object, root?: func \| object }	{}	The props used for each slot inside the Menu.
slots	{ listbox?: elementType, root?: elementType }	{}	The components used for each slot inside the Menu. Either a string to use a HTML element or a component. See Slots API below for more details.

The ref is forwarded to the root element.

To learn how to customize the slot, check out the Overriding component structure guide.

Name	Default class	Default HTML tag	Description
root	.MuiMenu-root	PopperUnstyled	The component that renders the root.
listbox	.MuiMenu-listbox	'ul'	The component that renders the listbox.

You can override the style of the component using one of these customization options:

With a global class name.
With a rule name as part of the component's styleOverrides property in a custom theme.

These class names are useful for styling with CSS. They are applied to the root slot when specific states are triggered.

Global class	Description
.Mui-expanded STATE	State class applied to the root `PopperUnstyled` element and the listbox `ul` element if `open={true}`.

import useMenu from '@mui/base/useMenu';
// or
import { useMenu } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Name	Type	Description
listboxId	string
listboxRef	React.Ref<any>
onClose	() => void
open	boolean

Name	Type	Description
contextValue	MenuUnstyledContextType	The value for the menu context.
getListboxProps	<TOther extends EventHandlers>(otherHandlers?: TOther) => UseMenuListboxSlotProps	Resolver for the listbox component's props.
highlightedOption	string \| null	The highlighted option in the menu listbox.
highlightFirstItem	() => void	Callback for highlighting the first item in the menu listbox.
highlightLastItem	() => void	Callback for highlighting the last item in the menu listbox.
menuItems	Record<string, MenuItemMetadata>	Items in the menu listbox.

import useMenuItem from '@mui/base/useMenuItem';
// or
import { useMenuItem } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Name	Type	Description
ref^*	React.Ref<any>
disabled	boolean
label	string
onClick	React.MouseEventHandler<any>

Name	Type	Default	Description
disabled	boolean	false	If `true`, the component is disabled.
focusVisible	boolean	false	If `true`, the component is being focused using keyboard.
getRootProps	<TOther extends EventHandlers = {}>(otherHandlers?: TOther) => UseMenuItemRootSlotProps<TOther>		Resolver for the root slot's props.
highlighted	boolean	false	If `true`, the component is being highlighted.

Unstyled Menu

Introduction

Components

Usage

Basics

Anatomy

Slot props

CSS classes

Hooks

Customization

Wrapping MenuItems

MenuItemUnstyled API

Import

Props

Slots

CSS classes

MenuUnstyled API

Import

Props

Slots

CSS classes

useMenu API

Import

Parameters

Return value

useMenuItem API

Import

Parameters

Return value