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 from Artifactory

• Verify that you have access to (https://docs.int.bayer.com/cloud/devops/artifactory/)[Bayer Artifactory]
  • Verify your token is correctly set up in your .npmrc as per the link above
• Verify you have the @element scope configured in your .npmrc
  • @element:registry=https://artifactory.bayer.com/artifactory/api/npm/npm-platforms-engineering/
• Install the component and themes bundles
  • npm i @element/react-components @element/themes
    • alternatively install the component individually along with the themes bundle npm i @element/react-menu @element/themes

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|string | 275 | false | Sets the max height of the menu. It can be a number or string with 100% or so. | | open | boolean | false | false | Controls the visibility of the menu. | | server | boolean | null | false | When set to to true ensures no browser-specific apis are accessed during initialisation. When set to false, ignored or set to null, no conditional rendering is applied. | | 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. |