Skip to content

Commit

Permalink
[docs] Add details on complementary Menu components (mui#44957)
Browse files Browse the repository at this point in the history
Signed-off-by: Sycamore <71297412+samuelsycamore@users.noreply.github.com>
  • Loading branch information
samuelsycamore authored Jan 9, 2025
1 parent 9900fcb commit 088bfa8
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 9 deletions.
22 changes: 14 additions & 8 deletions docs/data/material/components/menus/menus.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,19 @@ A menu displays a list of choices on a temporary surface. It appears when the us

{{"component": "@mui/docs/ComponentLinkHeader"}}

## Introduction

Menus are implemented using a collection of related components:

- Menu: The container/surface of the menu.
- Menu Item: An option for users to select from the menu.
- Menu List (optional): Alternative composable container for Menu Items—see [Composition with Menu List](#composition-with-menu-list) for details.

## Basic menu

A basic menu opens over the anchor element by default (this option can be [changed](#menu-positioning) via props). When close to a screen edge, a basic menu vertically realigns to make sure that all menu items are completely visible.

Choosing an option should immediately ideally commit the option and close the menu.

**Disambiguation**: In contrast to simple menus, simple dialogs can present additional detail related to the options available for a list item or provide navigational or orthogonal actions related to the primary task. Although they can display the same content, simple menus are preferred over simple dialogs because simple menus are less disruptive to the user's current context.
You should configure the component so that selecting an option immediately confirms it and closes the menu, as shown in the demo below.

{{"demo": "BasicMenu.js"}}

Expand Down Expand Up @@ -54,13 +60,13 @@ For instance, you can display the menu on top of the anchor:

{{"demo": "PositionedMenu.js"}}

## MenuList composition
## Composition with Menu List

The `Menu` component uses the `Popover` component internally.
However, you might want to use a different positioning strategy, or not blocking the scroll.
For answering those needs, we expose a `MenuList` component that you can compose, with `Popper` in this example.
The Menu component uses the Popover component internally.
But you might want to use a different positioning strategy, or prefer not to block scrolling, for example.

The primary responsibility of the `MenuList` component is to handle the focus.
The Menu List component lets you compose your own menu for these kinds of use cases—its primary purpose is to handle focus.
See the demo below for an example of composition that uses Menu List and replaces the Menu's default Popover with a Popper component instead:

{{"demo": "MenuListComposition.js", "bg": true}}

Expand Down
2 changes: 1 addition & 1 deletion docs/data/material/components/popper/popper.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Some important features of the Popper component:
- The scroll isn't blocked like with the [Popover](/material-ui/react-popover/) component.
The placement of the popper updates with the available area in the viewport.
- Clicking away does not hide the Popper component.
If you need this behavior, you can use the [Base UI Click-Away Listener](/base-ui/react-click-away-listener/) - see the example in the [menu documentation section](/material-ui/react-menu/#menulist-composition).
If you need this behavior, you can use the [Base UI Click-Away Listener](/base-ui/react-click-away-listener/) - see the example in the [menu documentation section](/material-ui/react-menu/#composition-with-menu-list).
- The `anchorEl` is passed as the reference object to create a new `Popper.js` instance.

{{"component": "@mui/docs/ComponentLinkHeader", "design": false}}
Expand Down

0 comments on commit 088bfa8

Please sign in to comment.