005cf56baf
Some checks failed
No response / noResponse (push) Has been cancelled
CI / Continuous releases (push) Has been cancelled
CI / test-dev (macos-latest) (push) Has been cancelled
CI / test-dev (ubuntu-latest) (push) Has been cancelled
CI / test-dev (windows-latest) (push) Has been cancelled
Maintenance / main (push) Has been cancelled
Scorecards supply-chain security / Scorecards analysis (push) Has been cancelled
CodeQL / Analyze (push) Has been cancelled
146 lines
4.8 KiB
Markdown
146 lines
4.8 KiB
Markdown
---
|
||
productId: joy-ui
|
||
title: React Menu component
|
||
components: Menu, MenuItem, MenuList, MenuButton
|
||
githubLabel: 'scope: menu'
|
||
waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/
|
||
---
|
||
|
||
# Menu
|
||
|
||
<p class="description">Menus display a list of choices on temporary surfaces.</p>
|
||
|
||
{{"component": "@mui/docs/ComponentLinkHeader"}}
|
||
|
||
## Introduction
|
||
|
||
Joy UI provides five menu-related components:
|
||
|
||
- Menu Button - a button that opens a menu. It reuses the styles from [`Button`](/joy-ui/react-button/).
|
||
- Menu - a listbox popup for wrapping the menu items which reuses the styles from [`List`](/joy-ui/react-list/).
|
||
- Menu Item - a menu item which reuses the styles from [`ListItemButton`](/joy-ui/react-list/).
|
||
- Menu List - a standalone listbox for composition usage. It also reuses the styles from [`List`](/joy-ui/react-list/).
|
||
- Dropdown - the outermost component that wires a button with a menu. It only provides a context and does not render anything.
|
||
|
||
{{"demo": "MenuUsage.js", "hideToolbar": true, "bg": "gradient"}}
|
||
|
||
## Component
|
||
|
||
After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements:
|
||
|
||
```jsx
|
||
import Menu from '@mui/joy/Menu';
|
||
import MenuButton from '@mui/joy/MenuButton';
|
||
import MenuItem from '@mui/joy/MenuItem';
|
||
import Dropdown from '@mui/joy/Dropdown';
|
||
|
||
export default function MyApp() {
|
||
return (
|
||
<Dropdown>
|
||
<MenuButton>Actions</MenuButton>
|
||
<Menu>
|
||
<MenuItem>Add item</MenuItem>
|
||
</Menu>
|
||
</Dropdown>
|
||
);
|
||
}
|
||
```
|
||
|
||
### Basic usage
|
||
|
||
Place both the Menu and Menu Button inside a Dropdown component.
|
||
This will wire them together.
|
||
The Menu Button will toggle the visibility of the menu and act as an anchor for the Menu's popup.
|
||
|
||
The basic version of the menu opens over the anchor element by default.
|
||
You can change this via [specific positioning props](#menu-positioning).
|
||
|
||
When close to the screen's edge, the menu vertically realigns to make sure that all menu items are completely visible.
|
||
Choosing an option should immediately, and ideally, commit the option and close the menu.
|
||
|
||
{{"demo": "BasicMenu.js"}}
|
||
|
||
### Sizes
|
||
|
||
The menu component comes with three sizes out of the box: `sm`, `md` (the default), and `lg`.
|
||
|
||
When specifying a size for the `Menu` component, menu items inside of it will inherit the value.
|
||
|
||
{{"demo": "SizeMenu.js"}}
|
||
|
||
:::info
|
||
To learn how to add more sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
|
||
:::
|
||
|
||
### Selected
|
||
|
||
Use the `selected` prop to signal whether a `MenuItem` is selected or not.
|
||
|
||
The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#interactive-list-items).
|
||
|
||
{{"demo": "SelectedMenu.js"}}
|
||
|
||
### Icon button menu
|
||
|
||
To use [IconButton](/joy-ui/react-button/#icon-button) component as a menu button, pass it to the root slot of the `MenuButton` component.
|
||
|
||
Use `slotProps` to pass props to the IconButton component.
|
||
|
||
{{"demo": "IconButtonMenu.js"}}
|
||
|
||
### Positioned menu
|
||
|
||
The `Menu` is based on the MUI Base `Popper` component, which exposes a few [placement props](https://v6.mui.com/base-ui/react-popper/#placement).
|
||
For example, this is how you'd go for displaying the menu on the bottom-end of the anchor button.
|
||
|
||
{{"demo": "PositionedMenu.js"}}
|
||
|
||
### Group menus
|
||
|
||
{{"demo": "GroupMenu.js"}}
|
||
|
||
### Controlling the open state
|
||
|
||
By default, the open/close state of the menu is managed internally by the Dropdown component.
|
||
To control it programmatically from the outside, apply the Dropdown's `open` and `onOpenChange` props as shown below:
|
||
|
||
{{"demo": "ControlledDropdown.js"}}
|
||
|
||
### `MenuList` composition
|
||
|
||
To get full control of the DOM structure, use the `MenuList` component.
|
||
You can use it to compose any popup-alike component.
|
||
The primary responsibility of this component is handling the focus state.
|
||
|
||
{{"demo": "MenuListComposition.js"}}
|
||
|
||
Or display the menu without a popup:
|
||
|
||
{{"demo": "MenuListGroup.js"}}
|
||
|
||
## Debugging
|
||
|
||
To keep the list box open for inspecting elements, enable the `Emulate a focused page` option from the [Chrome DevTool Rendering](https://developer.chrome.com/docs/devtools/rendering/apply-effects/#emulate-a-focused-page) tab.
|
||
You can also access this option by using [command menu and search for it](https://developer.chrome.com/docs/devtools/command-menu/).
|
||
|
||
## Common examples
|
||
|
||
### Apps menu
|
||
|
||
This example replicates a menu that contain links to other applications.
|
||
|
||
{{"demo": "AppsMenu.js"}}
|
||
|
||
### Menu bar
|
||
|
||
This example replicates the application menu bar on macOS.
|
||
It supports mouse and keyboard navigation between menu items.
|
||
|
||
{{"demo": "MenuToolbarExample.js"}}
|
||
|
||
### Side navigation icons
|
||
|
||
This example is quite common in dashboard applications where the side navigation is shrunk into icons, and the menu is triggered by hovering them.
|
||
|
||
{{"demo": "MenuIconSideNavExample.js"}}
|