@workday/canvas-kit-docs/dist/mdx/preview-react/menu/Menu.mdx

Documentation components of Canvas Kit components

import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
import {StatusIndicator} from '@workday/canvas-kit-preview-react/status-indicator';
import Basic from './examples/Basic';
import ContextMenu from './examples/ContextMenu';
import CustomMenuItem from './examples/CustomMenuItem';
import Icons from './examples/Icons';
import Headers from './examples/Headers';
import ManyItems from './examples/ManyItems';


# Canvas Kit Menu

<StatusIndicator variant="red">
  <StatusIndicator.Label>Deprecated</StatusIndicator.Label>
</StatusIndicator>

`Menu` in Preview been deprecated and will be removed in a future major version. Please use
[Menu in Main](https://workday.github.io/canvas-kit/?path=/docs/components-popups-menu--basic)
instead.

`DeprecatedMenu` displays a list of options when triggered by an action or UI element like an icon
or button.

[> Workday Design Reference](https://design.workday.com/components/popups/menus)

## Installation

```sh
yarn add @workday/canvas-kit-preview-react
```

## Usage

### Basic Example

`DeprecatedMenu` is typically triggered by an action such as pressing a button. Here's an example of
how you might implement that behavior using a [`Popup`](/components/popups/popup/).

<ExampleCodeBlock code={Basic} />

`DeprecatedMenu` will automatically assign focus to itself when it appears provided you set the
`isOpen` prop correctly, so you do **not** need to use the `useInitialFocus` `Popup` hook. You
**will**, however, need to use `useReturnFocus` to return focus back to the triggering button after
closing the `DeprecatedMenu`.

`DeprecatedMenu` follows the
[Actions Menu pattern](https://www.w3.org/TR/wai-aria-practices/examples/menu-button/menu-button-actions-active-descendant.html)
using `aria-activedescendant`. Below is table of supported keyboard shortcuts and associated
actions.

| Key                | Action                                                                                                                                           |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Enter` or `Space` | Activates the menu item and then closes the menu                                                                                                 |
| `Escape`           | Closes the menu                                                                                                                                  |
| `Up Arrow`         | Moves focus to the previous menu item – if focus is on first menu item, it moves focus to the last menu item                                     |
| `Down Arrow`       | Moves focus to the next menu item – if focus is on last menu item, it moves focus to the first menu item                                         |
| `Home`             | Moves focus to the first menu item                                                                                                               |
| `End`              | Moves focus to the last menu item                                                                                                                |
| `A-Z / a-z`        | Moves focus to the next menu item with a label that starts with the typed character if such an menu item exists – otherwise, focus does not move |

Note that although `DeprecatedMenu` includes support for keyboard shortcuts for the menu itself,
you'll need to add your own keyboard handling and aria attributes to the triggering button.

### Context Menu

<ExampleCodeBlock code={ContextMenu} />

### Custom Menu Item

`DeprecatedMenu` renders a styled `<ul>` element with a role of `menu`, and `DeprecatedMenuItem`s
are `<li>` elements with the correct attributes to ensure they are accessible. If you choose to
implement your own custom menu items, be sure to use semantic `<li>` elements with the following
attributes:

- `role="menuitem"`
- `tabindex={-1}`

Below is an example:

<ExampleCodeBlock code={CustomMenuItem} />

### Icons

<ExampleCodeBlock code={Icons} />

### Headers

You can group menu items logically by adding a `isHeader` attribute on your `<MenuItems>`. To make
your new items screen reader friendly add an `aria-label` around each grouped item.

<ExampleCodeBlock code={Headers} />

### Many Items

<ExampleCodeBlock code={ManyItems} />

## Component API

### DeprecatedMenu

<SymbolDoc name="DeprecatedMenu" fileName="/preview-react/" />

### DeprecatedMenuItem

<SymbolDoc name="DeprecatedMenuItem" fileName="/preview-react/" />