diff --git a/src/data/nav-items.yaml b/src/data/nav-items.yaml index b8ab6946b86..6c360b41be9 100644 --- a/src/data/nav-items.yaml +++ b/src/data/nav-items.yaml @@ -124,12 +124,14 @@ path: /components/loading/usage/ - title: Modal path: /components/modal/usage/ + - title: Menu + path: /components/menu/usage/ + - title: Menu buttons + path: /components/menu-buttons/usage/ - title: Notification path: /components/notification/usage/ - title: Number input path: /components/number-input/usage/ - - title: Overflow menu - path: /components/overflow-menu/usage/ - title: Pagination path: /components/pagination/usage/ - title: Popover diff --git a/src/pages/components/menu-buttons/accessibility.mdx b/src/pages/components/menu-buttons/accessibility.mdx new file mode 100644 index 00000000000..5b788d272a7 --- /dev/null +++ b/src/pages/components/menu-buttons/accessibility.mdx @@ -0,0 +1,93 @@ +--- +title: Menu buttons +description: + Menu buttons, including menu buttons, combo buttons, and overflow menus, open + a menu with a list of interactive options. +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + +import { + StructuredListWrapper, + StructuredListHead, + StructuredListBody, + StructuredListRow, + StructuredListInput, + StructuredListCell, + OrderedList, + ListItem, +} from '@carbon/react'; + + + +No accessibility annotations are needed for overflow menus, but keep these +considerations in mind if you are modifying Carbon or creating a custom +component. + + + + + +**Coming soon!** The accessibility information for the menu button and combo +button is going to be updated soon. + + + + + +What Carbon provides +Development considerations + + + +## What Carbon provides + +Carbon bakes keyboard operation into its components, improving the experience of +blind users and others who operate via keyboard. Carbon also incorporates other +accessibility considerations, some of which are described below. + +### Keyboard interaction + +Each overflow menu is in the tab order and is activated by `Space` or `Enter`. +When the menu is open, the first item takes focus. Focus is moved between menu +items with the `Up` and `Down` arrow keys. `Space` or `Enter` activates the item +with focus (which causes focus to go somewhere else and the menu to close). +`Esc` collapses the menu and puts focus onto the menu button. + + + + +![example of overflow menu keyboard interaction](images/overflow-menu-accessibility-1.png) + + + Overflow menus are reached by Tab. Space and Enter keys open the menu as well + as activating menu items with focus. + + + + + + + + +![illustration showing an open menu with the focus on the first item, and the arrow and Esc keys called out](images/overflow-menu-accessibility-2.png) + + + When opened, the first item in the menu takes focus. Arrow keys move focus, + Esc closes the menu. + + + + + +## Development considerations + +Keep these considerations in mind if you are modifying Carbon or creating a +custom component. + +- Overflow menus are buttons with `aria-haspopup` set to "true". +- The overflow menu is named with `aria-label`. +- Each menu item is an `li` in a `ul`. +- Each list item contains a button with `role="menuitem"` and `tabindex="-1"`. + See the + [ARIA authoring practices on menubutton](https://w3c.github.io/aria-practices/#menubutton) + for more considerations. diff --git a/src/pages/components/menu-buttons/code.mdx b/src/pages/components/menu-buttons/code.mdx new file mode 100644 index 00000000000..4207209e662 --- /dev/null +++ b/src/pages/components/menu-buttons/code.mdx @@ -0,0 +1,181 @@ +--- +title: Menu buttons + +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + + + +Preview the menu button, combo button, and overflow menu component with the +React live demo. For detailed code usage documentation, see the Storybooks for +each framework below. + + + +## Documentation + +### Menu button + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +### Combo button + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +### Overflow menu + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +## Live demo + + diff --git a/src/pages/components/overflow-menu/images/overflow-menu-accessibility-1.png b/src/pages/components/menu-buttons/images/overflow-menu-accessibility-1.png similarity index 100% rename from src/pages/components/overflow-menu/images/overflow-menu-accessibility-1.png rename to src/pages/components/menu-buttons/images/overflow-menu-accessibility-1.png diff --git a/src/pages/components/overflow-menu/images/overflow-menu-accessibility-2.png b/src/pages/components/menu-buttons/images/overflow-menu-accessibility-2.png similarity index 100% rename from src/pages/components/overflow-menu/images/overflow-menu-accessibility-2.png rename to src/pages/components/menu-buttons/images/overflow-menu-accessibility-2.png diff --git a/src/pages/components/menu-buttons/images/popover-usage-4.png b/src/pages/components/menu-buttons/images/popover-usage-4.png new file mode 100644 index 00000000000..919cbb35cb5 Binary files /dev/null and b/src/pages/components/menu-buttons/images/popover-usage-4.png differ diff --git a/src/pages/components/menu-buttons/images/style-combo-button.png b/src/pages/components/menu-buttons/images/style-combo-button.png new file mode 100644 index 00000000000..58ea52efd84 Binary files /dev/null and b/src/pages/components/menu-buttons/images/style-combo-button.png differ diff --git a/src/pages/components/menu-buttons/images/style-menu-button-sizes.png b/src/pages/components/menu-buttons/images/style-menu-button-sizes.png new file mode 100644 index 00000000000..74fe2ff57e4 Binary files /dev/null and b/src/pages/components/menu-buttons/images/style-menu-button-sizes.png differ diff --git a/src/pages/components/menu-buttons/images/style-menu-buttons.png b/src/pages/components/menu-buttons/images/style-menu-buttons.png new file mode 100644 index 00000000000..22a2c480cc8 Binary files /dev/null and b/src/pages/components/menu-buttons/images/style-menu-buttons.png differ diff --git a/src/pages/components/menu-buttons/images/style-overflow-menu.png b/src/pages/components/menu-buttons/images/style-overflow-menu.png new file mode 100644 index 00000000000..2e30e69f992 Binary files /dev/null and b/src/pages/components/menu-buttons/images/style-overflow-menu.png differ diff --git a/src/pages/components/menu-buttons/images/style-structure-combo-button.png b/src/pages/components/menu-buttons/images/style-structure-combo-button.png new file mode 100644 index 00000000000..e9cd8f14a12 Binary files /dev/null and b/src/pages/components/menu-buttons/images/style-structure-combo-button.png differ diff --git a/src/pages/components/menu-buttons/images/style-structure-menu-button.png b/src/pages/components/menu-buttons/images/style-structure-menu-button.png new file mode 100644 index 00000000000..7367f29e1b4 Binary files /dev/null and b/src/pages/components/menu-buttons/images/style-structure-menu-button.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-alignment-menu-button-alternatives.png b/src/pages/components/menu-buttons/images/usage-menu-alignment-menu-button-alternatives.png new file mode 100644 index 00000000000..821afc01382 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-alignment-menu-button-alternatives.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-alignment-menu-button-default.png b/src/pages/components/menu-buttons/images/usage-menu-alignment-menu-button-default.png new file mode 100644 index 00000000000..ef52b0b1ab1 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-alignment-menu-button-default.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-button-1.png b/src/pages/components/menu-buttons/images/usage-menu-button-1.png new file mode 100644 index 00000000000..5743decd8b1 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-button-1.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-button-2.png b/src/pages/components/menu-buttons/images/usage-menu-button-2.png new file mode 100644 index 00000000000..05748956279 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-button-2.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-button-3.png b/src/pages/components/menu-buttons/images/usage-menu-button-3.png new file mode 100644 index 00000000000..2e0f45a6d81 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-button-3.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-button-4.png b/src/pages/components/menu-buttons/images/usage-menu-button-4.png new file mode 100644 index 00000000000..2b335fc55ce Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-button-4.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-button-5.png b/src/pages/components/menu-buttons/images/usage-menu-button-5.png new file mode 100644 index 00000000000..ffcbeceac90 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-button-5.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-button-anatomy.png b/src/pages/components/menu-buttons/images/usage-menu-button-anatomy.png new file mode 100644 index 00000000000..e47cde8b7d9 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-button-anatomy.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-button-height.png b/src/pages/components/menu-buttons/images/usage-menu-button-height.png new file mode 100644 index 00000000000..cccc872dae9 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-button-height.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-button-overview.png b/src/pages/components/menu-buttons/images/usage-menu-button-overview.png new file mode 100644 index 00000000000..ed06515893f Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-button-overview.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-combo-button-1.png b/src/pages/components/menu-buttons/images/usage-menu-combo-button-1.png new file mode 100644 index 00000000000..41c1875caf1 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-combo-button-1.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-combo-button-2.png b/src/pages/components/menu-buttons/images/usage-menu-combo-button-2.png new file mode 100644 index 00000000000..d53df225888 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-combo-button-2.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-combo-button-3.png b/src/pages/components/menu-buttons/images/usage-menu-combo-button-3.png new file mode 100644 index 00000000000..8c814030885 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-combo-button-3.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-do.png b/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-do.png new file mode 100644 index 00000000000..1c683e4871b Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-do.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-dont.png b/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-dont.png new file mode 100644 index 00000000000..5559f1df7af Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-dont.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-keyboard-combo-button.png b/src/pages/components/menu-buttons/images/usage-menu-keyboard-combo-button.png new file mode 100644 index 00000000000..b3a7c323864 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-keyboard-combo-button.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-keyboard-menu-button.png b/src/pages/components/menu-buttons/images/usage-menu-keyboard-menu-button.png new file mode 100644 index 00000000000..6bef05b0222 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-keyboard-menu-button.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-mouse-combo-button.png b/src/pages/components/menu-buttons/images/usage-menu-mouse-combo-button.png new file mode 100644 index 00000000000..e9ea83dcc68 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-mouse-combo-button.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-mouse-keyboard-overflow-menu.png b/src/pages/components/menu-buttons/images/usage-menu-mouse-keyboard-overflow-menu.png new file mode 100644 index 00000000000..2764c586c2d Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-mouse-keyboard-overflow-menu.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-placement-1.png b/src/pages/components/menu-buttons/images/usage-menu-placement-1.png new file mode 100644 index 00000000000..5adad252acd Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-placement-1.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-placement-2.png b/src/pages/components/menu-buttons/images/usage-menu-placement-2.png new file mode 100644 index 00000000000..a77599ea10d Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-placement-2.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-width-do-1.png b/src/pages/components/menu-buttons/images/usage-menu-width-do-1.png new file mode 100644 index 00000000000..05cccdb2890 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-width-do-1.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-width-do-2.png b/src/pages/components/menu-buttons/images/usage-menu-width-do-2.png new file mode 100644 index 00000000000..ca11226c4d8 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-width-do-2.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-width-dont-1.png b/src/pages/components/menu-buttons/images/usage-menu-width-dont-1.png new file mode 100644 index 00000000000..51440d91d14 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-width-dont-1.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-width-dont-2.png b/src/pages/components/menu-buttons/images/usage-menu-width-dont-2.png new file mode 100644 index 00000000000..6a8b1e1792a Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-width-dont-2.png differ diff --git a/src/pages/components/menu-buttons/images/usage-menu-width-menu-button-default.png b/src/pages/components/menu-buttons/images/usage-menu-width-menu-button-default.png new file mode 100644 index 00000000000..8d20cabae8b Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-width-menu-button-default.png differ diff --git a/src/pages/components/menu-buttons/images/usage-overflow-1.png b/src/pages/components/menu-buttons/images/usage-overflow-1.png new file mode 100644 index 00000000000..36a6ec4e68a Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-overflow-1.png differ diff --git a/src/pages/components/menu-buttons/images/usage-overflow-2.png b/src/pages/components/menu-buttons/images/usage-overflow-2.png new file mode 100644 index 00000000000..2d65774decf Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-overflow-2.png differ diff --git a/src/pages/components/menu-buttons/images/usage-overflow-3.png b/src/pages/components/menu-buttons/images/usage-overflow-3.png new file mode 100644 index 00000000000..634a7c414fe Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-overflow-3.png differ diff --git a/src/pages/components/menu-buttons/images/usage-overflow-menu.png b/src/pages/components/menu-buttons/images/usage-overflow-menu.png new file mode 100644 index 00000000000..d0a7ffe0335 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-overflow-menu.png differ diff --git a/src/pages/components/menu-buttons/images/usage-overview.png b/src/pages/components/menu-buttons/images/usage-overview.png new file mode 100644 index 00000000000..cd365b6386e Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-overview.png differ diff --git a/src/pages/components/menu-buttons/images/usage-popover.png b/src/pages/components/menu-buttons/images/usage-popover.png new file mode 100644 index 00000000000..919cbb35cb5 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-popover.png differ diff --git a/src/pages/components/menu-buttons/images/usage-sizing-height-do.png b/src/pages/components/menu-buttons/images/usage-sizing-height-do.png new file mode 100644 index 00000000000..6d49919f82b Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-sizing-height-do.png differ diff --git a/src/pages/components/menu-buttons/images/usage-sizing-height-dont.png b/src/pages/components/menu-buttons/images/usage-sizing-height-dont.png new file mode 100644 index 00000000000..ac6bbeea072 Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-sizing-height-dont.png differ diff --git a/src/pages/components/menu-buttons/style.mdx b/src/pages/components/menu-buttons/style.mdx new file mode 100644 index 00000000000..59c059affe9 --- /dev/null +++ b/src/pages/components/menu-buttons/style.mdx @@ -0,0 +1,133 @@ +--- +title: Menu buttons +description: + Menu buttons, including menu buttons, combo buttons, and overflow menus, open + a menu with a list of interactive options. +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + + + +The following page documents visual specifications such as color, typography, +structure, and size. + + + + + +Color Typography +Structure Size +Feedback + + + +## Color + +Enabled and interactive states of menu buttons follow the +[button style](https://carbondesignsystem.com/components/button/style) +guidelines. Menu buttons can use primary, tertiary, or ghost buttons. Combo +buttons can only use a primary button. Overflow menu can only use a ghost +button. + +The menu used in menu buttons should follow the +[menu style](/components/menu/style). + +### Menu button color + + + + +![Menu button variants](images/style-menu-buttons.png) + + + + +Example of menu button using three different types of buttons + +### Combo button color + + + + +![Combo button](images/style-combo-button.png) + + + + +Example of a combo button using a primary button + +### Overflow menu color + + + + +![Overflow menu](images/style-overflow-menu.png) + + + + + + Overflow menu appears as a ghost button when closed and once it opens the + color changes to the correct `$layer` color token to match the menu. + + +## Typography + +| Element | Font-size (px/rem) | Font-weight | Type token | +| ---------------- | ------------------ | ------------- | ------------------ | +| Button text | 14 / 0.875 | Regular / 400 | `$body-compact-01` | +| Menu option text | 14 / 0.875 | Regular / 400 | `$body-compact-01` | + +## Structure + +The structure of menu buttons should follow the +[button style](https://carbondesignsystem.com/components/button/style) +guidelines. + +### Menu button + +
+ +![Menu button structure](images/style-structure-menu-button.png) + +
+ + + Menu button in default width (left) and menu button in fluid width (right) + + +### Combo button + +
+ +![Combo button structure](images/style-structure-combo-button.png) + +
+ + + Combo button in default width (left) and menu button in fluid width (right) + + +## Size + +There are three +[button](https://carbondesignsystem.com/components/button/style/#sizes) sizes: +small, medium, and large. + +| Elements | Size | Height (px/rem) | +| -------- | ----------- | --------------- | +| Button | Small (sm) | 32 / 2 | +| | Medium (md) | 40 / 2.5 | +| | Large (lg) | 48 / 3 | + +
+ +![Menu button sizes](images/style-menu-button-sizes.png) + +
+ +## Feedback + +Help us improve this component by providing feedback, asking questions, and +leaving any other comments on +[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). diff --git a/src/pages/components/menu-buttons/usage.mdx b/src/pages/components/menu-buttons/usage.mdx new file mode 100644 index 00000000000..72d969d28a4 --- /dev/null +++ b/src/pages/components/menu-buttons/usage.mdx @@ -0,0 +1,636 @@ +--- +title: Menu buttons +description: + Menu buttons, including menu buttons, combo buttons, and overflow menus, open + a menu with a list of interactive options. +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + + + +Menu buttons, including menu buttons, combo buttons, and overflow menus, open a +menu with a list of interactive options. + + + + + +**New in Carbon v11!** Apart from the overflow menu, the menu button and combo +button components have been added to our system and they are only available in +v11. + + + + + +Overview +Live demo +Formatting +Content +Universal behaviors +Menu button +Combo button +Overflow menu +Related +References +Feedback + + + +## Overview + +There are three variants of menu buttons (or menu triggers): menu button, combo +button, and overflow menu button. Menu buttons are comprised of a button and a +[menu](/components/menu/usage/), which can be clicked to trigger an action or +selected to initiate an action from a menu. + + + + +![Overview image of menu buttons](images/usage-menu-button-overview.png) + + + + +### When to use + +#### Hiding extra actions in limited screen space + +Menu button, combo button, and overflow menu are useful when you need to show +numerous options but have limited screen space available to display them. By +hiding less frequently used or advanced options until the user needs them, it +avoids cluttering the main interface with too many options. + +| Variant | Purpose | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Menu button](#menu-button) | Use a menu button when all actions in the menu list share the same level of importance. They are usually used in the page header. | +| [Combo button](#combo-button) | Use a combo button when screen real estate is limited and one of the actions has particular importance. They are usually used in the page header. | +| [Overflow menu](#overflow-menu) | Use an overflow menu when additional options are available to the user and there is a space constraint. They are usually used in rows or cards. | + +## Live demo + + + +## Formatting + +### Anatomy + + + + +![Menu button anatomy diagram](images/usage-menu-button-anatomy.png) + + + + + + + +#### 1. Menu button + +A. Primary button
C. Menu
+ +#### 2. Combo button + +A. Primary button
B. Icon button
C. Menu
+ + + + + +#### 3. Overflow menu + +A. Icon button
C. Menu
+ + + + +### Sizing + +#### Height + +Menu items come in four sizes: extra small, small, medium, and large. See more +about size specifications on the [style](/components/menu/style/) tab. When +using a menu button trigger, the height of the menu item (singular) reflects the +size of the button being used. + + + +**Note** Currently, Carbon does not support the extra small size for +[buttons](https://carbondesignsystem.com/components/button/usage/), only for +rows or menu items. Therefore, this menu size cannot be utilized with menu +button triggers. However, the extra small menu size remains available for +implementation in other contexts if needed. + + + +| Size | Height (px / rem) | +| ----------- | ----------------- | +| Extra small | 24 / 1.5 | +| Small | 32 / 2 | +| Medium | 40 / 2.5 | +| Large | 48 / 3 | + + + + +![Menu height](images/usage-menu-button-height.png) + + + + + + + +![Do match the height of the menu buttons and the menu](images/usage-sizing-height-do.png) + + + + +![Do not mix the height of the menu buttons and the menu](images/usage-sizing-height-dont.png) + + + + +#### Width + +By default, the [menu button](/components/menu-buttons/usage/#menu-button) and +[combo button](/components/menu-buttons/usage/#combo-button) follow the +[button structure style](https://carbondesignsystem.com/components/button/style#structure), +and the menu maintains a minimum width of 160px to prevent a narrow appearance. + + + + +![Menu width](images/usage-menu-width-menu-button-default.png) + + + Menu default width when both button label and menu option labels are short + + + + + +If the menu item labels become longer, the menu button and combo button remain +the same size while the menu component can expand up to a maximum of 288px. +Conversely, if the button labels become longer, the menu component should not +appear narrower but should extend to match the width of the menu buttons. + +If you opt for +[fluid-width default buttons](https://carbondesignsystem.com/components/button/usage/#alignment), +both the menu button (or the combo button) and the menu should have the same +width. + + + + +![Do use the minimum width of menu](images/usage-menu-width-do-1.png) + + + + +![Do not narrow the menu to fit with other elements](images/usage-menu-width-dont-1.png) + + + + + + + +![Do match the width when the menu button or combo button labels become longer](images/usage-menu-width-do-2.png) + + + + +![Do not make the menu appear shorter than the menu button or combo button](images/usage-menu-width-dont-2.png) + + + + +Ghost buttons only adhere to the +[button](https://carbondesignsystem.com/components/button/style/) style. This is +because enlarging the ghost button's width to match the menu's width would +result in the caret appearing disconnected from its associated button, +especially when the menu button is in its closed state. + + + + +![Do use default ghost button in all cases](images/usage-menu-ghost-button-width-do.png) + + + + +![Do not use fluid ghost button in any cases](images/usage-menu-ghost-button-width-dont.png) + + + + +### Alignment + +#### Default + +By default, combo button, menu button, or overflow button remains positioned at +the top, to the left or right side of the menu when it is open, depending on the +available space and layout. + + + + +![Menu default alignments](images/usage-menu-alignment-menu-button-default.png) + + + + +#### Alternatives + +Alternatively, open menus can be positioned at the bottom, to the left or right +of its associated menu button trigger, depending on the available space and +layout. + + + + +![Menu alternative alignments](images/usage-menu-alignment-menu-button-alternatives.png) + + + + +### Placement + +#### Menu and combo buttons + +These buttons are ideal for page headers, where multiple, distinct actions may +impact the page content, and where real-estate is limited. In the page header +component, multiple buttons will become a single action button at smaller screen +sizes. These buttons should only be used when the actions affect a full page or +a large object on a page (examples include a canvas UI, diagram, or whole data +table). + + + + +![Menu button alignment example](images/usage-menu-placement-1.png) + + + + +#### Overflow menu + +When actions affect a smaller proportion of a page, such as table rows or cards, +use an overflow menu. + + + + +![Overflow menu alignment example](images/usage-menu-placement-2.png) + + + + +## Content + +### Main elements + +#### Label + +The text label of the button is important to communicate the action that is +triggered when the user interacts with it. The text label must accurately +describe the button action or indicate that interacting with it displays a list +of possible actions. + +### Further guidance + +For further content guidance, see Carbon's +[content guidelines](/guidelines/content/overview). + +## Universal behaviors + +### States + +The default and interactive states of menu buttons should follow the button +[style](https://carbondesignsystem.com/components/button/style) guidelines. + +- Combo buttons are available only as primary buttons. +- Menu buttons come in three different button types: primary, tertiary, and + ghost. +- The icon button of overflow menu is treated as the ghost button, displaying + only an icon and following its designated color and style. + +### Interactions + +#### Menu button + +Users can reveal the menu by: + +- Clicking anywhere on the container of a menu button +- Or tabbing into the menu button and pressing `Return` or `Enter` + + + + +![Menu button interactions](images/usage-menu-keyboard-menu-button.png) + +Mouse and keyboard interactions for menu button + + + +#### Combo button + +Users can reveal the menu by: + +- Clicking anywhere on the container of the primary button or the icon button. + If clicking on the primary button, this will apply to certain elements, + depending on user interaction. +- Or tabbing into the combo button which will focus on the primary button first + then the icon button. Then, pressing the `Return` or `Enter` to trigger the + action of the primary button or menu under the icon button. + + + + +![Combo button mouse interaction](images/usage-menu-mouse-combo-button.png) + +Mouse interactions for combo button + + + + + + +![Combo button keyboard interaction](images/usage-menu-keyboard-combo-button.png) + +Keyboard interactions for combo button + + + +#### Overflow menu + +Users can reveal the overflow menu by: + +- Clicking anywhere on the container of the icon button +- Or tabbing into the icon button and pressing `Return` or `Enter` + + + + +![Overflow menu mouse and keyboard interactions](images/usage-menu-mouse-keyboard-overflow-menu.png) + +Keyboard interactions for overflow menu + + + +## Menu button + +Menu buttons group actions that share the same level of importance. The icon +used within the menu button should always be a caret in order to visually convey +to the user that there are options to select from. There are three main use +cases where using a menu button is recommended: + +- Grouping objects with the same common action +- Actions related to a common label +- Distinct actions applied to the same object or page + +Menu button and combo button come in three different button types: primary, +tertiary, and ghost. + + + + +![An example of menu button](images/usage-menu-button-1.png) + + + + +### Best practices + +#### Grouping objects with the same common action + +Menu buttons are effective when a single action affects multiple distinct +objects. This is particularly applicable when users need to Create or Add +various objects, and all these objects are equally relevant options. + +The shared action should not be repeated in the menu list. This adds unnecessary +clutter and makes each option less distinct at a glance. + + + + +![Do add distinct items for the action](images/usage-menu-button-2.png) + + + + +![Do not repeat the action in the action item](images/usage-menu-button-3.png) + + + + +#### Actions associated with a shared label + +Another common use of a menu button is grouping actions related to a common +label. An example of this is when users have multiple approaches to execute an +action, all of which are presented as choices within the menu button. + + + + +![Actions associated with a shared label](images/usage-menu-button-4.png) + + + + +#### Distinct actions applied to the same object or page + +In many cases, actions on a page may not use the same verb or have a shared +label for the menu button. When grouped actions remain distinct, consider +labeling the menu button as 'Actions' to encompass all available choices. + + + + +![Distinct actions applied to the same object or page](images/usage-menu-button-5.png) + +Example shows the menu button with possible actions that could influence the data within tab contents + + + +## Combo button + +A combo button is composed of two buttons: the left is the default option (the +most commonly used selection), and the right (chevron icon) shows the rest of +the available options. A combo button provides quick access to a default action +while also offering a list of related actions or options. + +The combo button is expected to have less use than the menu button, as the +additional actions are more hidden than they would be in menu button. However, +this button does have particular use where screen real estate is limited and one +of the actions has particular importance. + +Combo button has only one button type: primary. + + + + +![An example of combo button](images/usage-menu-combo-button-1.png) + + + + +### Best practices + +#### Choose a default action + +Remember to choose the default, primary action that will be displayed in the +primary button so it is not hidden within the menu of additional actions. The +primary default action is typically the most commonly used action there is to +take. + + + + +![Choose a default action](images/usage-menu-combo-button-2.png) + + + Example shows that users mostly choose to save records, while less common + options are hidden as extra actions. + + + + +#### Reduce visual complexity on a page + +Combo buttons reduce visual complexity by grouping similar commands together. +For example, how navigation menus group together related options to enable +conceptual understanding of the site information structure. + + + + +![Reduce visual complexity on a page](images/usage-menu-combo-button-3.png) + + + Example shows that many actions (ghost buttons) applying to the same data can + be replaced by the combo button. + + + + +## Overflow menu + +Overflow menu is also another option that is available to the user when there is +a space constraint, usually used in data table rows or in cards. Overflow menu +has the ghost button style only. + + + + +![An example of overflow menu](images/usage-overflow-1.png) + + + + +### Best practices + +#### Overflow menu in cards + +When there are more than three interactive icons, consider moving less important +ones into the overflow menu. The overflow menu then takes the place of a third +action. + + + + +![An example of overflow menu in cards](images/usage-overflow-2.png) + + + + +#### Overflow menu icon + +The overflow icon can be customized to align with the product's requirements. +However, it's advisable to make minimal changes to the overflow menu's icon to +maintain consistency across the product and ensure a consistent user experience. + + + + +![An example of another overflow menu icon](images/usage-overflow-3.png) + + + + +#### Overflow versus tab tip (popover) + +Overflow menu displays extra options with simple text, typically utilized within +data table rows or cards. The +[tab tip](https://carbondesignsystem.com/components/popover/usage/#tab-tip) +popover allows the user to include more complex inputs such as a checkbox group +or a radio button group, usually connected to a data table toolbar. + + + + +![An example of overflow menu](images/usage-overflow-menu.png) + +Use overflow menus in data table row + + + + +![An example of a popover](images/usage-popover.png) + +Use a popover in the data table toolbar + + + +## Related + +#### Menu + +To learn more about the details of how to use the menu component correctly, see +[menu buttons](/components/menu-buttons/usage). + +#### Dropdown + +To understand how the menu component can be used differently from the dropdown +component, see [dropdown](/components/dropdown/usage). + +#### Popover + +The popover component is visually similar to menu, but is used for different +purposes. See [popover](/components/dropdown/usage) for more information. + +## References + +- Anna Kaley, + [Contextual Menus: Delivering Relevant Tools for Tasks](https://www.nngroup.com/articles/contextual-menus/) + (Nielsen Norman Group, 2019) + +- Page Laubheimer, + [Split Buttons: Definition](https://www.nngroup.com/articles/split-buttons/) + (Nielsen Norman Group, 2019) + +## Feedback + +Help us improve this component by providing feedback, asking questions, and +leaving any other comments on +[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). diff --git a/src/pages/components/menu/accessibility.mdx b/src/pages/components/menu/accessibility.mdx new file mode 100644 index 00000000000..a214b1d32f0 --- /dev/null +++ b/src/pages/components/menu/accessibility.mdx @@ -0,0 +1,11 @@ +--- +title: Menu +description: +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + + + +**Coming soon!** This page is a work in progress. + + diff --git a/src/pages/components/menu/code.mdx b/src/pages/components/menu/code.mdx new file mode 100644 index 00000000000..d4a9b089f05 --- /dev/null +++ b/src/pages/components/menu/code.mdx @@ -0,0 +1,76 @@ +--- +title: Menu + +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + + + +Preview the menu component with the React live demo. For detailed code usage +documentation, see the Storybooks for each framework below. + + + +## Documentation + +### Menu + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +## Live demo + + diff --git a/src/pages/components/menu/images/style-menu-default-state.png b/src/pages/components/menu/images/style-menu-default-state.png new file mode 100644 index 00000000000..3f5a23c1e41 Binary files /dev/null and b/src/pages/components/menu/images/style-menu-default-state.png differ diff --git a/src/pages/components/menu/images/style-menu-interactive-states.png b/src/pages/components/menu/images/style-menu-interactive-states.png new file mode 100644 index 00000000000..1a48acc4017 Binary files /dev/null and b/src/pages/components/menu/images/style-menu-interactive-states.png differ diff --git a/src/pages/components/menu/images/style-menu-size.png b/src/pages/components/menu/images/style-menu-size.png new file mode 100644 index 00000000000..4eb52184276 Binary files /dev/null and b/src/pages/components/menu/images/style-menu-size.png differ diff --git a/src/pages/components/menu/images/style-menu-structure-items-submenu.png b/src/pages/components/menu/images/style-menu-structure-items-submenu.png new file mode 100644 index 00000000000..be3a6c31925 Binary files /dev/null and b/src/pages/components/menu/images/style-menu-structure-items-submenu.png differ diff --git a/src/pages/components/menu/images/style-menu-structure-items.png b/src/pages/components/menu/images/style-menu-structure-items.png new file mode 100644 index 00000000000..0aa3cc1acac Binary files /dev/null and b/src/pages/components/menu/images/style-menu-structure-items.png differ diff --git a/src/pages/components/menu/images/style-menu-structure-submenus.png b/src/pages/components/menu/images/style-menu-structure-submenus.png new file mode 100644 index 00000000000..255f87b9096 Binary files /dev/null and b/src/pages/components/menu/images/style-menu-structure-submenus.png differ diff --git a/src/pages/components/menu/images/style-menu-structure.png b/src/pages/components/menu/images/style-menu-structure.png new file mode 100644 index 00000000000..5a0e9a68ddc Binary files /dev/null and b/src/pages/components/menu/images/style-menu-structure.png differ diff --git a/src/pages/components/menu/images/usage-image-submenus-title-do.png b/src/pages/components/menu/images/usage-image-submenus-title-do.png new file mode 100644 index 00000000000..eaf06828e2f Binary files /dev/null and b/src/pages/components/menu/images/usage-image-submenus-title-do.png differ diff --git a/src/pages/components/menu/images/usage-image-submenus-title-dont.png b/src/pages/components/menu/images/usage-image-submenus-title-dont.png new file mode 100644 index 00000000000..bc22a36cbdd Binary files /dev/null and b/src/pages/components/menu/images/usage-image-submenus-title-dont.png differ diff --git a/src/pages/components/menu/images/usage-interactions-mouse.png b/src/pages/components/menu/images/usage-interactions-mouse.png new file mode 100644 index 00000000000..7426f879778 Binary files /dev/null and b/src/pages/components/menu/images/usage-interactions-mouse.png differ diff --git a/src/pages/components/menu/images/usage-menu-RTL.png b/src/pages/components/menu/images/usage-menu-RTL.png new file mode 100644 index 00000000000..5702114790d Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-RTL.png differ diff --git a/src/pages/components/menu/images/usage-menu-alignment-item-do.png b/src/pages/components/menu/images/usage-menu-alignment-item-do.png new file mode 100644 index 00000000000..0c27df09fb9 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-alignment-item-do.png differ diff --git a/src/pages/components/menu/images/usage-menu-alignment-item-dont.png b/src/pages/components/menu/images/usage-menu-alignment-item-dont.png new file mode 100644 index 00000000000..623743d2a6a Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-alignment-item-dont.png differ diff --git a/src/pages/components/menu/images/usage-menu-alignment-menu-button-alternatives.png b/src/pages/components/menu/images/usage-menu-alignment-menu-button-alternatives.png new file mode 100644 index 00000000000..821afc01382 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-alignment-menu-button-alternatives.png differ diff --git a/src/pages/components/menu/images/usage-menu-alignment-menu-button-default.png b/src/pages/components/menu/images/usage-menu-alignment-menu-button-default.png new file mode 100644 index 00000000000..ef52b0b1ab1 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-alignment-menu-button-default.png differ diff --git a/src/pages/components/menu/images/usage-menu-alignment-menu-buttons-alternatives.png b/src/pages/components/menu/images/usage-menu-alignment-menu-buttons-alternatives.png new file mode 100644 index 00000000000..821afc01382 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-alignment-menu-buttons-alternatives.png differ diff --git a/src/pages/components/menu/images/usage-menu-alignment-menu-buttons-default.png b/src/pages/components/menu/images/usage-menu-alignment-menu-buttons-default.png new file mode 100644 index 00000000000..ef52b0b1ab1 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-alignment-menu-buttons-default.png differ diff --git a/src/pages/components/menu/images/usage-menu-anatomy.png b/src/pages/components/menu/images/usage-menu-anatomy.png new file mode 100644 index 00000000000..547198d3173 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-anatomy.png differ diff --git a/src/pages/components/menu/images/usage-menu-danger-state.png b/src/pages/components/menu/images/usage-menu-danger-state.png new file mode 100644 index 00000000000..4b6650c82cb Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-danger-state.png differ diff --git a/src/pages/components/menu/images/usage-menu-divider.png b/src/pages/components/menu/images/usage-menu-divider.png new file mode 100644 index 00000000000..9c618a9d368 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-divider.png differ diff --git a/src/pages/components/menu/images/usage-menu-ghost-button-width-do.png b/src/pages/components/menu/images/usage-menu-ghost-button-width-do.png new file mode 100644 index 00000000000..1c683e4871b Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-ghost-button-width-do.png differ diff --git a/src/pages/components/menu/images/usage-menu-ghost-button-width-dont.png b/src/pages/components/menu/images/usage-menu-ghost-button-width-dont.png new file mode 100644 index 00000000000..5559f1df7af Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-ghost-button-width-dont.png differ diff --git a/src/pages/components/menu/images/usage-menu-height.png b/src/pages/components/menu/images/usage-menu-height.png new file mode 100644 index 00000000000..cccc872dae9 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-height.png differ diff --git a/src/pages/components/menu/images/usage-menu-multi-select.png b/src/pages/components/menu/images/usage-menu-multi-select.png new file mode 100644 index 00000000000..505d3796aef Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-multi-select.png differ diff --git a/src/pages/components/menu/images/usage-menu-number-items-do.png b/src/pages/components/menu/images/usage-menu-number-items-do.png new file mode 100644 index 00000000000..77131e0cb1b Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-number-items-do.png differ diff --git a/src/pages/components/menu/images/usage-menu-number-items-dont.png b/src/pages/components/menu/images/usage-menu-number-items-dont.png new file mode 100644 index 00000000000..1960b9238fb Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-number-items-dont.png differ diff --git a/src/pages/components/menu/images/usage-menu-ordering.png b/src/pages/components/menu/images/usage-menu-ordering.png new file mode 100644 index 00000000000..b4e01bc91a2 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-ordering.png differ diff --git a/src/pages/components/menu/images/usage-menu-overflow-truncate.png b/src/pages/components/menu/images/usage-menu-overflow-truncate.png new file mode 100644 index 00000000000..d374af83c5d Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-overflow-truncate.png differ diff --git a/src/pages/components/menu/images/usage-menu-overview.png b/src/pages/components/menu/images/usage-menu-overview.png new file mode 100644 index 00000000000..c5d46abac10 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-overview.png differ diff --git a/src/pages/components/menu/images/usage-menu-shortcut.png b/src/pages/components/menu/images/usage-menu-shortcut.png new file mode 100644 index 00000000000..31cfbc31743 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-shortcut.png differ diff --git a/src/pages/components/menu/images/usage-menu-single-select.png b/src/pages/components/menu/images/usage-menu-single-select.png new file mode 100644 index 00000000000..690f980f001 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-single-select.png differ diff --git a/src/pages/components/menu/images/usage-menu-width-do-1.png b/src/pages/components/menu/images/usage-menu-width-do-1.png new file mode 100644 index 00000000000..05cccdb2890 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-width-do-1.png differ diff --git a/src/pages/components/menu/images/usage-menu-width-do-2.png b/src/pages/components/menu/images/usage-menu-width-do-2.png new file mode 100644 index 00000000000..ca11226c4d8 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-width-do-2.png differ diff --git a/src/pages/components/menu/images/usage-menu-width-dont-1.png b/src/pages/components/menu/images/usage-menu-width-dont-1.png new file mode 100644 index 00000000000..51440d91d14 Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-width-dont-1.png differ diff --git a/src/pages/components/menu/images/usage-menu-width-dont-2.png b/src/pages/components/menu/images/usage-menu-width-dont-2.png new file mode 100644 index 00000000000..6a8b1e1792a Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-width-dont-2.png differ diff --git a/src/pages/components/menu/images/usage-menu-width-menu-button-default.png b/src/pages/components/menu/images/usage-menu-width-menu-button-default.png new file mode 100644 index 00000000000..8d20cabae8b Binary files /dev/null and b/src/pages/components/menu/images/usage-menu-width-menu-button-default.png differ diff --git a/src/pages/components/menu/images/usage-sizing-height-do.png b/src/pages/components/menu/images/usage-sizing-height-do.png new file mode 100644 index 00000000000..6d49919f82b Binary files /dev/null and b/src/pages/components/menu/images/usage-sizing-height-do.png differ diff --git a/src/pages/components/menu/images/usage-sizing-height-dont.png b/src/pages/components/menu/images/usage-sizing-height-dont.png new file mode 100644 index 00000000000..ac6bbeea072 Binary files /dev/null and b/src/pages/components/menu/images/usage-sizing-height-dont.png differ diff --git a/src/pages/components/menu/style.mdx b/src/pages/components/menu/style.mdx new file mode 100644 index 00000000000..bec74a9790f --- /dev/null +++ b/src/pages/components/menu/style.mdx @@ -0,0 +1,166 @@ +--- +title: Menu +description: + A menu is a list of interactive options that appears when users interact with + an element or perform a specific action. +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + + + +The following page documents visual specifications such as color, typography, +structure, and size. + + + + + +Color Typography +Structure Size +Feedback + + + +## Color + +| Elements | Property | Color token | +| ------------- | ---------------- | -------------------------- | +| Menu option | background-color | `$layer` \* | +| | text-color | `$text-secondary` | +| | border-top | `$border-subtle` \* | +| Caret icon | svg | `$icon-secondary` | +| Shortcut icon | svg | `$icon-secondary` | +| Container | box-shadow | 0 2px 6px 0 rgba(0,0,0,.2) | + + + * Denotes a contextual color token that will change values based on the layer + it is placed on. + + + + + +![Menu default state](images/style-menu-default-state.png) + + + + +### Interactive state color + +| State | Element | Property | Color token | +| ---------------------- | ----------- | ---------------- | ----------------- | +| Hover | Menu option | background-color | `$layer-hover` \* | +| | Menu option | text-color | `$text-primary` | +| | Icon | svg | `$icon-primary` | +| Focus | Menu option | background-color | `$layer`\* | +| | Menu option | border | `$focus` | +| Focus and hover | Menu option | background-color | `$layer-hover` \* | +| | Menu option | text-color | `$text-primary` | +| | Icon | svg | `$icon-primary` | +| | Menu option | border | `$focus` | +| Danger hover | Menu option | background-color | `$support-error` | +| | Menu option | text-color | `$text-on-color` | +| | Icon | svg | `$icon-on-color` | +| Danger hover and focus | Menu option | background-color | `$support-error` | +| | Menu option | text-color | `$text-on-color` | +| | Menu option | border | `$focus` | +| | Icon | svg | `$icon-on-color` | +| Disabled | Menu option | background-color | `$layer` \* | +| | Menu option | text-color | `$text-disabled` | +| | Icon | svg | `$icon-disabled` | + + + * Denotes a contextual color token that will change values based on the layer + it is placed on. + + + + + +![Menu interactive states](images/style-menu-interactive-states.png) + + + + +## Typography + +| Element | Font-size (px/rem) | Font-weight | Type token | +| ---------------- | ------------------ | ------------- | ------------------ | +| Menu option text | 14 / 0.875 | Regular / 400 | `$body-compact-01` | + +## Structure + +| Element | Property | px / rem | Spacing token | +| ---------------------------------- | ---------------------------- | ---------------- | ---------------------------- | +| Icon | icon size | 16 / 1 | – | +| Option (default) | padding-right, padding-left | 16 / 1 | `$spacing-05` | +| Option (selectable but unselected) | padding-right, padding-left | 16 / 1, 40 / 2.5 | `$spacing-05`, `$spacing-08` | +| Option (selectable and selected) | padding-right, padding-left | 16 / 1 | `$spacing-05` | +| Option (next to the divider) | margin-top, or margin-bottom | 4 / .25 | `$spacing-02` | +| Option (first and last) | margin-top, or margin-bottom | 4 / .25 | `$spacing-02` | +| Divider | margin-top | 1px | – | + +### Default menu structure + +
+ +![Default menu structure](images/style-menu-structure.png) + +
+ +Structure and spacing measurements for main menu + +### Submenu structure + +
+ +![Submenu structure](images/style-menu-structure-submenus.png) + +
+ +Structure and spacing measurements for submenu + +### Menu option structure + +
+ +![Default menu option structure](images/style-menu-structure-items.png) + +
+ +
+ +![Selected menu option structure](images/style-menu-structure-items-submenu.png) + +
+ + + Structure and spacing measurements for individual menu options + + +## Size + +There are four menu option sizes: extra small, small, medium, and large. The +height of a menu is determined by a +[menu button](/components/menu-buttons/style/). Menus have a fixed minimum width +of 160px (or 10rem), to ensure menu items have sufficient horizontal space, +while also having a fixed maximum width of 288px (or 18rem). + +| Elements | Size | Height (px/rem) | +| ----------- | ---------------- | --------------- | +| Menu option | Extra small (xs) | 24 / 1.5 | +| | Small (sm) | 32 / 2 | +| | Medium (md) | 40 / 2 .5 | +| | Large (lg) | 48 / 3 | + +
+ +![Menu sizes](images/style-menu-size.png) + +
+ +## Feedback + +Help us improve this component by providing feedback, asking questions, and +leaving any other comments on +[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). diff --git a/src/pages/components/menu/usage.mdx b/src/pages/components/menu/usage.mdx new file mode 100644 index 00000000000..2dbe10bb1a7 --- /dev/null +++ b/src/pages/components/menu/usage.mdx @@ -0,0 +1,588 @@ +--- +title: Menu +description: + A menu is a list of interactive options that appears when users interact with + an element or perform a specific action. +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + + + +A menu is a list of interactive options that appears when users interact with an +element or perform a specific action. + + + + + +**New in Carbon v11!** Menu is a new component we have added to our system and +is only available in v11. + + + + + +Overview +Live demo +Formatting +Content +Universal behaviors +Modifiers +Related +References +Feedback + + + +## Overview + +A menu is a disclosure component that appears with a set of actions relevant to +a specific control, interface area, data element, or application view. +Typically, this context is determined by the user's current selection prior to +invoking the menu. Menus can be opened from components such as menu buttons or +through right-clicking. + +This guidance will help you understand how to format, structure, and use the +menu component effectively. + + + + +![Overview image of menu](images/usage-menu-overview.png) + + + + +### When to use + +#### Declutter interface + +In general, use menus to hide less frequently used or advanced options until +users specifically need them. This keeps the interface clean and focused on +essential elements. + +#### Context menu + +Context menus are triggered by a right-click interaction. A context menu is a +defined list of options in a menu that appears above all other content on a page +and is related to the selected content or element it was triggered from. + +#### Customizable actions + +Menus can speed up interactions for advanced users who are already familiar with +the application. These users often rely on shortcuts and context-specific +actions to work more efficiently. + +### When not to use + +#### Form submission + +When submitting a form with a static list of options for users to choose from, +or when filtering, use a +[dropdown](https://www.carbondesignsystem.com/components/dropdown/usage) instead +of a menu. + +#### Complex inputs + +When many or complex inputs are used collectively, use a +[popover](https://www.carbondesignsystem.com/components/popover/usage) instead +of a menu. + + + +## Formatting + +### Anatomy + + + + +![Menu anatomy diagram](images/usage-menu-anatomy.png) + + + + +1. **Trigger**: Elements that are triggered to display a list of available + actions. These menu triggers can include a menu button, a combo button, and + an overflow menu within menu buttons. Menus can also be opened when + right-clicking on a page or specific element, like a column, or a row. + +2. **Action item**: A menu item that can be activated to apply its action on + certain elements. This item can be accompanied by a submenu indicator or + keyboard shortcuts. + +3. **Divider**: A rule that indicates different sections within the menu. + +4. **Submenu indicator**: A caret icon that indicates a submenu. + +5. **Keyboard shortcut**: Certain action items may also have keyboard shortcuts. + +6. **Menu**: A container displays the open state and contains a list of actions + that can be selected. + +7. **Selected item**: An item that can be selected. The selection can be single + or multi-selected. + +8. **Submenu**: A nested level off of the primary level. + +### Sizing + +#### Height + +Menu items come in four sizes: extra small, small, medium, and large. See more +about size specifications on the +[style](https://www.carbondesignsystem.com/components/menu/style) tab. When +using a menu button trigger, the height of the menu item (singular) reflects the +size of the button being used. + + + +**Note** Currently, Carbon does not support the extra-small size for +[buttons](https://carbondesignsystem.com/components/button/usage/), only for +rows or menu items. Therefore, this menu size cannot be utilized with menu +button triggers. However, the extra-small menu size remains available for +implementation in other contexts if needed. + + + +| Size | Height (px / rem) | +| ----------- | ----------------- | +| Extra small | 24 / 1.5 | +| Small | 32 / 2 | +| Medium | 40 / 2.5 | +| Large | 48 / 3 | + + + + +![Menu height](images/usage-menu-height.png) + + + + + + + +![Do match the height of the menu buttons and the menu](images/usage-sizing-height-do.png) + + + + +![Do not mix the height of the menu buttons and the menu](images/usage-sizing-height-dont.png) + + + + +#### Width + +By default, the [menu button](/components/menu-buttons/usage/#menu-button) and +[combo button](/components/menu-buttons/usage/#combo-button) follow the +[button structure style](/components/button/style#structure), and the menu +maintains a minimum width of 160px to prevent a narrow appearance. + + + + +![Menu width](images/usage-menu-width-menu-button-default.png) + + + Menu default width when both button label and menu option labels are short + + + + + +If the menu item labels become longer, the menu button and combo button remain +the same size, while the menu component can expand up to a maximum of 288px. +Conversely, if the button labels become longer, the menu component should not +appear narrower but should extend to match the width of the menu buttons. + +If you opt for +[fluid-width default buttons](https://carbondesignsystem.com/components/button/usage/#alignment), +both the menu button (or the combo button) and the menu should have the same +width. + + + + +![Do use the minimum width of menu](images/usage-menu-width-do-1.png) + + + + +![Do not narrow the menu to fit with other elements](images/usage-menu-width-dont-1.png) + + + + + + + +![Do match the width when the menu button or combo button labels become longer](images/usage-menu-width-do-2.png) + + + + +![Do not make the menu appear shorter than the menu button or combo button](images/usage-menu-width-dont-2.png) + + + + +Ghost buttons only adhere to the +[button](https://carbondesignsystem.com/components/button/usage/) style. This is +because enlarging the ghost button's width to match the menu's width would +result in the caret appearing disconnected from its associated button, +especially when the menu button is in its closed state. + + + + +![Do use default ghost button in all cases](images/usage-menu-ghost-button-width-do.png) + + + + +![Do not use fluid ghost button in any cases](images/usage-menu-ghost-button-width-dont.png) + + + + +### Alignment + +#### Default + +By default, combo button, menu button, or overflow button remains positioned at +the top, to the left or right side of the menu when it is open, depending on the +available space and layout. + + + + +![Menu default alignments](images/usage-menu-alignment-menu-button-default.png) + + + Menu default width when both button label and menu item labels are short{' '} + + + + + +#### Alternatives + +Alternatively, open menus can be positioned at the bottom, to the left or right +of its associated menu button trigger, depending on the available space and +layout. + + + + +![Menu alternative alignments](images/usage-menu-alignment-menu-button-alternatives.png) + + + + +#### Action items + +Ensuring consistent alignment when combining single or multi-select items with +non-select items will improve the menu's readability. + + + + +![Do create a consistent alignment with unselected and selected items](images/usage-menu-alignment-item-do.png) + + + + +![Do not create mixed alignments with unselected and selected items](images/usage-menu-alignment-item-dont.png) + + + + +#### Right to left (RTL) + +For RTL (right-to-left) languages, the entire menu is mirrored horizontally, +including the direction of the caret and keyboard shortcuts. + + + + +![Menu alignment right to left](images/usage-menu-RTL.png) + + + + +## Content + +### Main elements + +#### Overflow + +Consider using short and precise labels for menu items. However, when deciding +to truncate long menu items, use a tooltip on hover to reveal the full text. + + + + +![An overflow example for menu items](images/usage-menu-overflow-truncate.png) + +Tooltip helps clarify the truncated text + + + +#### Ordering and grouping + +To aid discoverability, arrange menu items in a meaningful sequence that aligns +with the order of operations. To help users focus on the most relevant options, +place the ones used most often at the top. + +When there is a significant amount of menu items, it's advisable to group them +into sections, separated by divider lines. + + + + +![Ordering and grouping](images/usage-menu-ordering.png) + + + Example shows how menu items are grouped into meaningful sections + + + + +#### Number of items within a menu + +Expansive lists of options in menus can overwhelm users. With context menu and +overflow menu, keep the list length manageable by including no more than 12 +items to help users scan through items easily without having to scroll. With +[menu buttons](/components/menu-buttons/usage), keep the menu list smaller with +under 5 items. + + + + +![Do consider including as fewer items as possible](images/usage-menu-number-items-do.png) + + + Do consider including as few items as possible + + + + + +![Do not overload choices](images/usage-menu-number-items-dont.png) + + + Do not overload choices + + + + +### Submenus + +A submenu is a menu item with the caret icon on the right, offering additional +related commands. While submenus can help tidy up a context menu and make its +options clearer, introducing multiple levels of submenus can make the user +experience more complex and harder to navigate. Avoid multiple levels of nesting +when it comes to submenus. + +#### Actions associated with a shared label + +When a term appears in more than two menu items in the same group, consider +eliminating the recurring term in the submenu label to help people predict its +content and scan easily. + + + + +![Do omit recurring term](images/usage-image-submenus-title-do.png) + + + + +![Do not repeat the same term from the submenu trigger](images/usage-image-submenus-title-dont.png) + + + + +### Further guidance + +For further content guidance, see Carbon's +[content guidelines](/guidelines/content/overview). + +## Universal behaviors + +### States + +Menu items have seven states: **enabled**, **hover**, **focus**, **focus** and +**hover**, **danger hover**, **danger hover and focus**, and **disabled**. Learn +more about states on the [style](/components/menu/style/) tab. + +| State | When to use | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _Enabled_ | When an action in the list is live but a user is not directly interacting with it. This is commonly referred to as the default or normal state of the component. | +| _Hover_ | When a user’s mouse cursor is hovering over the menu item in menus or submenus. | +| _Focus_ | When a user tabs to or clicks on a menu trigger. This will open up the menu list. The first item in the menu list has the focus state as default. | +| _Focus and hover_ | When an item is in the focus state but the user’s mouse cursor is hovering over the item row. | +| _Danger hover_ | When an action could have destructive effects on the user’s data (for example, delete or remove). | +| _Danger hover and focus_ | When a user tabs to a destructive menu item that has the danger hover state. | +| _Disabled_ | When an action is not able to be performed at a certain time, but will be possible to be performed by that user, at another point in time. Actions that are permissions-based should be hidden if it is never possible for a user to perform that action. | + +### Interactions + +#### Mouse + +Once the menu opens by clicking on a menu button trigger or right-clicking on an +area, users can: + +- Select or deselect an item by clicking on it +- Hover over the item with the caret icon to reveal additional options or + actions from that item +- Click outside of the menu area to close it + + + + +![Mouse interactions on menus](images/usage-interactions-mouse.png) + +Mouse interactions on menu + + + +#### Keyboard + +Once the menu opens by pressing `Return` or `Enter` on the menu trigger, users +can: + +- Press `Up` and `Down` arrows to navigate between menu options +- Press `Return` or `Enter` or `Right` arrow on the item with the caret icon to + reveal additional options +- Press `Return` or `Enter` on an item to select or deselect it +- Press `Escape` to close it + +### Responsive behaviors + +Once the menu opens, the first option is highlighted. Users can then move +through the list of options to activate or select one item at a time. Once users +activate or select a menu item, the menu closes. + +Activating a menu item can trigger the following: + +- Open a dialog box +- Set a value (which can perform an action or serve as a selected/deselected + option in the menu) +- Open a new page (typically in a new window or tab) +- Initiate a new user task (potentially involving multiple steps) +- Save or close something +- Expand a submenu (though this can also occur without activation) +- Undo or redo a user action +- Perform various actions (e.g., editing actions like cut, paste, copy, format; + application actions such as checking for updates) +- Open a sidebar or toolbar +- Access an existing page +- Adjust the current window(s) (e.g., minimize, split, arrange, swap) +- No action other than closing the menu + +## Modifiers + +#### Dividers + +Divider lines serve the purpose of categorizing related actions into appropriate +sections, while also distinguishing actions that might have a significant impact +on the user's data, such as deleting an app or service. + + + + +![Divider in menus](images/usage-menu-divider.png) + + + + +#### Keyboard shortcuts + +A menu item can display related values, like a caret indicator for accessing a +submenu or a keyboard shortcut linked to the action. + + + + +![Divider in menus](images/usage-menu-shortcut.png) + + + + +### Single-select and multi-select + +Single-select or multi-select has the same visual with the checkmark in front of +the menu item. + + + + +![Single-select example](images/usage-menu-single-select.png) + + + + + +![Multi-select example](images/usage-menu-multi-select.png) + + + + +### Danger state + +A danger hover state can be applied to actions that could cause significant +changes, such as delete. + + + + +![Danger state example](images/usage-menu-danger-state.png) + + + + +## Related + +#### Menu buttons + +To understand how to use menus with other specific menu button triggers, see +[menu buttons](/components/menu-buttons/usage). + +#### Dropdown + +To understand how the menu component can be used differently from the dropdown +component, see [dropdown](/components/dropdown/usage). + +#### Popover + +The popover component is visually similar to menu, but is used for different +purposes. See [popover](/components/dropdown/usage) for more information. + +## References + +- Anna Kaley, + [Contextual Menus: Delivering Relevant Tools for Tasks](https://www.nngroup.com/articles/contextual-menus/) + (Nielsen Norman Group, 2019) + +- Michael Villar, + [Building like it's 1984: A comprehensive guide to creating intuitive context menus](https://height.app/blog/guide-to-build-context-menus#:~:text=Context%20menus%20are%20menus%20that,different%20operating%20systems%20and%20apps.) + (Height, 2022) + +## Feedback + +Help us improve this component by providing feedback, asking questions, and +leaving any other comments on +[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).