Menu

Description

A menu displays a list of choices on a temporary surface. They allow users make a selection from multiple options. Menus appear when users interact with a button, action, or other control. Mostly commonly used with the List component.

See live demos on storybook

Storybook Menu Demos

Install bundle from npm-e

npm i @element-public/react-components @element-public/themes

Optional: install the component individually

npm i @element-public/react-menu @element-public/themes

Open ~/.npmrc in an editor and add the following line to enable the @element-public scope:

@element-public:registry=https://npm.platforms.engineering

Troubleshooting

See below if you have never installed a package from Bayer's npm-enterprise or run into the following error:

npm ERR! code E401
npm ERR! Unable to authenticate, your authentication token seems to be invalid.
npm ERR! To correct this please trying logging in again with:
npm ERR!     npm login

Setup an access token

See the devtools npm-e guide to learn how to create an access token if this is the first time you are using a npm-e package at Bayer or you do not have a line that starts with the following in your ~/.npmrc file:

//npm.platforms.engineering/:_authToken=

Notes

A Menu displays content on a temporary surface. Menus can be static or have interactable components. Menus can appear in various places on a page and can be opened, closed, or changed in other ways with Buttons or Icon Buttons. A Menu is positioned in the top left corner of the screen by default but can be moved using the absolutePositionX and absolutePositionY props. Additionally, the direction prop dictates in which direction the Menu opens, left to right or right to left.

Menus can be implemented in many ways. First, the "Surface Only" story demonstrates a Menu that opens without input from a Button.

The "Selectable Menu" stories show a Menu that opens when a user clicks a Button and that includes a List of clickable options. This Menu is anchored to the Button.

The "Hoisted Menu" stories show Menus that are anchored to the trigger, but hoisted to the body. While the hoisted Menu will be absolutely positioned by the anchor, it actually renders to the body. Thus allowing it to be visible even if the anchor is inside an element with overflow:hidden or a Table cell.

Usage

Menu can be used with many other components. The most common use cases include using Menu with Icon Button, List, and Table. For instance, a Menu can open as a result of clicking on an Icon Button, as shown on the "Icon Button Menu" Storybook tab. Also, Menus can include Lists as content or be included in a Table as a way of showing additional information when opened. Examples of these behaviors can be found under various Storybook story tabs.

Menu Props

| Name | Type | Default | Required | Description | | ----------------- | ------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | absolutePositionX | number | null | false | The horizontal position of the menu, when visible. The menu surface will be hoisted to the body of the DOM. This should only be used when the menu needs to be explicitly positioned and cannot be combined with MenuAnchor. | | absolutePositionY | number | null | false | The vertical position of the menu, when visible. The menu surface will be hoisted to the body of the DOM. This should only be used when the menu needs to be explicitly positioned and cannot be combined with MenuAnchor. | | anchorCorner | string | 'BOTTOM_START' | false | Sets the display position of the menu relative to the parent element. It must be used with Menu Anchor.Accepted Values: TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT, TOP_START, TOP_END, BOTTOM_START, BOTTOM_END | | anchorMargin | object | null | false | Sets the distance from the anchor point that the menu surface should be shown. The object properties should include at least one of top, bottom, left or right. | | anchorProps | object | {} | false | Custom props to be sent to the MenuAnchor wrapper of the trigger | | direction | string | 'ltr' | false | Sets the direction property for the menu. For right to left languages use rtl.Accepted Values: ltr, rtl | | fixed | boolean | false | false | Prevents the use of absolute position (x/y) props. | | fullScreen | boolean | false | false | Sets the width of the menu to the full width of the body. It is to be used with hoistToBody. Useful when creating navigation menus for mobile devices. | | fullWidth | boolean | false | false | Sets the width of the menu to the full width of the parent. Cannot be used with hoistToBody or when absolutePositionY or absolutePositionY is set. | | hoistToBody | boolean | false | false | Enables the menu to be rendered as part of the body, enables higher z-index. Requires surfaceOnly to be true. This can improve menu to behavior better inside a table. Use with caution: may cause unintended side-effects. | | maxHeight | number | 275 | false | Sets the max height of the menu. | | open | boolean | false | false | Controls the visibility of the menu. | | style | object | null | false | Passthrough style object. | | surfaceOnly | boolean | false | false | Renders as just the menu surface. While Menu expects a list of items, when surfaceOnly is true any content can go inside the menu. | | themeColor | string | 'surface' | false | Background color of the menu.Accepted Values: surface, primary, secondary | | wrapFocus | boolean | true | false | When used with a List component wrapFocus allows keyboard navigation to jump to the top or bottom of the list to enable continuous navigation. |

Menu Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ---------------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Expects a List or ListGroup component but accepts any valid markup or components. | | trigger | React.ReactNode | null | false | Node used to trigger open the menu or menu surface. Will also serve as the anchor. |

Menu Events

| Name | Default | Required | Params | Description | | --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | handleBodyClick | null | false | | Fired when html body is clicked. Default behavior is to close the menu. | | onClose | null | false | | Fired after the menu surface is closed. For best performance, this method should be memoized or wrapped with useCallback. | | onOpen | null | false | | Fired after the menu surface is opened. For best performance, this method should be memoized or wrapped with useCallback. | | onSelect | null | false | 1. Name: index, Type: number, Description: Index of selected List Item,2. Name: item, Type: DOM Element, Description: The DOM element selected. | Fired when a menu item is selected . It is not available if surfaceOnly is true. For best performance, this method should be memoized or wrapped with useCallback. |

Menu Breaking Changes

| Description | | ---------------------------------------------------------------------------------------------------- | | flush (removed): No longer needed. | | iconMenu (removed): No longer needed. | | unexposed (removed): Use anchorCorner instead. Set to "TOP_LEFT", or "TOP_START" to overlap button |

Menu Anchor Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ---------------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Expects a clickable component such as Button or IconButton and the Menu component. |