Menu

What is this?

Menu triggers allow merchants to open a dropdown and start contextual actions that are rarely used or repeated for each item in a list.

Composition

Name	Description
MenuButton	Button that triggers the menu popover
Menu	Menu's popover
MenuItem	Represents a button rendered inside the MenuList
MenuDivider	Represents an hr used to separate the menu popover into sections

Variants

MenuButton has four possible variants: primary, secondary, tertiary and neutralTertiary. Primary is the default variant.

Sizes

MenuButton has two possible sizes: normal and large. Normal is the default size.

Icon only

You can use the labelHidden property to hide the MenuButton label

Custom

It possible to use the label MenuButton property to set the button text. When a custom label is used, the icon changes to the IconCaretDown/Up.

Disabled

Disable the MenuButton by setting the disabled property to true.

Bleed

MenuButton can trespass the parent padding for some alignment and layout reasons, it is possible to achieve this behavior through the bleedX and bleedY property.

Item

MenuItem has two possible variants: neutral and critical, to enable the critical variant, the critical property needs to be true.

Item click

It is possible to set a custom action when a item is clicked.

Item disabled

Disable the MenuItem by setting the disabled property to true.

Usage

import {
  MenuButton,
  Menu,
  MenuItem,
  MenuDivider,
  useMenuState,
} from '@vtex/admin-ui'

function Example() {
  const state = useMenuState()

  return (
    <>
      <MenuButton state={state} />
      <Menu state={state}>
        <MenuItem label="Create" icon={<IconPlus />} />
        <MenuItem label="Edit" icon={<IconPencil />} />
        <MenuItem label="Download" icon={<IconArrowLineDown />} />
      </Menu>
    </>
  )
}

MenuButton Props

Name	Type	Description	Required	Default
state	MenuStateReturn	useMenuState hook return	✅	-
size	normal, large	Button size	🚫	normal
variant	primary, secondary, tertiary, neutralTertiary	Button variant	🚫	primary
label	string	Button label	🚫	More actions
labelHidden	boolean	Whether the label is visible or not	🚫	false
bleedX	boolean	Whether the Button should trespass the parent paddingX	🚫	false
bleedY	booelean	Whether the Button should trespass the parent paddingY	🚫	false

Menu Props

Name	Type	Description	Required	Default
state	MenuStateReturn	useMenuState hook return	✅	-

MenuItem Props

Name	Type	Description	Required	Default
label	string	Item label	✅	-
icon	ReactNode	Item icon	🚫	-
critical	boolean	Whether the item variant is critical	🚫	false

Accessibility

• Menu has role menu.
• MenuItem has role menuitem.
• Pressing Enter on MenuButton opens the Menu and places focus on its first item.
• When MenuItem has focus, Space and Enter triggers it.

Best Practices

You must always set the aria-label property in the Menu component.

function Example() {
  const state = useMenuState()

  return (
    <>
      <MenuButton state={state} />
      <Menu aria-label="actions" state={state}>
        <MenuItem label="Create" icon={<IconPlus />} />
        <MenuItem label="Edit" icon={<IconPencil />} />
        <MenuItem label="Download" icon={<IconArrowLineDown />} />
        <MenuDivider />
        <MenuItem label="Delete" icon={<IconTrash />} critical />
      </Menu>
    </>
  )
}

Keyboard Navigation

• ↓ moves focus to the next `MenuItem`.
• ↑ moves focus to the previous `MenuItem`.

Components

When to use the Tab, the Button, or a group of Buttons instead of the Menu?

• Choose the Tab component for navigation triggers that alternate between related views within the same container.
• Choose the Button when there is only one action trigger.
• Choose a group of Buttons when the group will not be repeated in a list and all its actions are frequently used.

Variants

When should a Menu be primary, secondary, or tertiary?

This answer depends on research to understand how frequently merchants use an action. Even so, there are patterns you can follow:

• When the most frequent action of the page leads to a menu with complementary options, use a primary Menu. For example, a Menu with the Create page label that leads to options such as Landing page and Category page.
• There should be only one primary action visible at a time.
• A Menu should never be secondary.

When should a Menu be neutral tertiary?

• When the same Menu is repeated, such as for each list item.
• When there is a group of tertiary Buttons and a Menu, they all should be neutral.
• When the container background uses the $bg.secondary color.

When should a Menu Item be critical?

A Menu Item should be critical when the Menu Item triggers an irreversible action. Actions should be reversible whenever possible and not require a critical color.

What to avoid:

Don’t use critical colors for Move to trash triggers that imply the possibility of reverting the action.

What should be the Menu’s size?

Use the large size for all primary Menu components. Use the normal size for tertiary Menu components.

Where should an icon be positioned in a Menu?

• When using the default More actions label, position the icon to the left.
• When using a custom label, position the icon to the right.

Position

When should I use more than one Menu?

Use more than one Menu component in a list when it is necessary to repeat the same set of actions for different objects. For example, in each row of a table.

What to avoid:

Don't use more than one Menu in the same container.

Where should the Menu be positioned in a container?

Considering left-to-right interfaces, follow these recommendations:

• Align the Menu to the right. For example, a Menu in the header of a Card should be vertically-centered and aligned to the right.
• In a group of actions, position the Menu as the last action.
• When a tertiary Menu is next to other content, ignore the Menu's box to align based on the Menu's icon and/or label. Use the bleed prop to implement this alignment.

Behavior

When to use a disabled Menu?

Never use a disabled Menu. Leave the Menu enabled and disable the items inside according to our recommendations.

When to use a disabled Menu Item?

• Use a disabled Menu Item only if, in some condition, it becomes enabled. For example, a Publish button that is only enabled when edits have been made.
• When the reason why an action is disabled might be unclear, leave the action enabled and show a modal explaining the reason on trigger.

What to avoid:

• Don't display a Tooltip when hovering a disabled Menu Item.

Content

What should be the label of a Menu?

The default label of a menu is More actions. A custom label should only be used when the Menu represents an action with complementary options. For example, a Menu with the label Create page that includes the options Landing page and Category page.

When writing a custom label, consider the following recommendations:

• Reuse existing labels.
• Always include a verb in the infinitive and an object. For example, Create product.
• Use a verb that reflects the exact action that the Menu triggers for every Menu Item. For example, use the label Create promotion for a Menu where the items are the different promotion types that can be created.
• Use sentence case but capitalize proper nouns.

What to avoid:

• Don’t use punctuation.
• Don’t use more than three words.
• Don’t use personal pronouns.

What should be the label of a Menu?

• Reuse existing labels.
• Always include a verb in the infinitive, except for when the Menu Item is inside a Menu with a custom label where the action is already defined in the Menu label.
• When the context already has a label for the object, remove the object from the label. For example, use Edit instead of Edit product.
• Leave the object explicit when the Menu has the same action for different objects, such as Edit product and Edit SKUs.
• Use a verb that reflects the exact action that the Menu Item triggers. For example, use Rename instead of Change name.
• Use sentence case but capitalize proper nouns.

What to avoid:

• Don’t use punctuation.
• Don’t use more than three words.
• Don’t use personal pronouns.

When should I hide Menu Items icons?

Hide icons of Menu Items whenever they are in a Menu with a custom label, since they will always trigger variations of the action that is in the Menu label.

When should a Menu have a hidden label and only an icon visible?

When the same Menu is repeated multiple times on a screen, such as for each list item.

What to avoid:

• Don't hide the label of a Menu with a custom label.
• Don’t use a Tooltip to display the label.

When to use a divider to separate Menu Items?

Use a divider to separate regular actions from destructive actions. For example, a Delete action in a Menu should be the last one, and there should be a divider above it.

• What is this?
• Composition
• Variants
• Sizes
• Icon only
• Custom
• Disabled
• Bleed
• Item
• Item click
• Item disabled