MenuItem | Mineral UI

A MenuItem represents an option in a Menu. They can be used to trigger actions or navigate to a new location. MenuItems provide context through optional variants, secondary text, or Icons.

A custom rendering hook is exposed to enable any extra functionality your app requires.

Examples #

Import Syntax #

import Menu, { MenuItem } from 'mineral-ui/Menu';

Basic Usage #

MenuItems are used to trigger an action or navigate to a new location.

Note

MenuItems normally occupy the full available width of their container. The MenuItems here are width-constrained for illustration purposes.

Light years

Star stuff

Encyclopaedia galactica

<DemoLayout>
  <Menu>
    <MenuItem>
      Light years
    </MenuItem>
    <MenuItem>
      Star stuff
    </MenuItem>
    <MenuItem>
      Encyclopaedia galactica
    </MenuItem>
  </Menu>
</DemoLayout>

Secondary Text #

A MenuItem can render secondary text, which will wrap when necessary. Use secondary text to give hints about extra functionality or show app status related to the action.

Light yearsStar stuff

Harvesting onlyDistant epochs

Encyclopaedia galacticaCosmic ocean

<DemoLayout>
  <Menu>
    <MenuItem secondaryText="Star stuff">
      Light years
    </MenuItem>
    <MenuItem secondaryText="Distant epochs">
      Harvesting only
    </MenuItem>
    <MenuItem secondaryText="Cosmic ocean">
      Encyclopaedia galactica
    </MenuItem>
  </Menu>
</DemoLayout>

Variants #

Use available variants to help communicate purpose. A startIcon will be automatically inserted to reinforce the intent.

Danger

Success

Warning

<DemoLayout>
  <Menu>
    <MenuItem variant="danger">
      Danger
    </MenuItem>
    <MenuItem variant="success">
      Success
    </MenuItem>
    <MenuItem variant="warning">
      Warning
    </MenuItem>
  </Menu>
</DemoLayout>

Menu Items with Icons #

A MenuItem can display an Icon at its start, end, or both. If both startIcon and variant props are provided, startIcon will be used.

Start icon

End icon

Both icons

Danger

Success

Warning

Disabled

() => {
  const icon = <IconCloud />;

  return (
    <DemoLayout>
      <Menu>
        <MenuItem iconStart={icon}>Start icon</MenuItem>
        <MenuItem iconEnd={icon}>End icon</MenuItem>
        <MenuItem iconStart={icon} iconEnd={icon}>Both icons</MenuItem>
      </Menu>
      <Menu>
        <MenuItem iconStart={icon} variant="danger">Danger</MenuItem>
        <MenuItem iconStart={icon} variant="success">Success</MenuItem>
        <MenuItem iconStart={icon} variant="warning">Warning</MenuItem>
        <MenuItem iconStart={icon} disabled>Disabled</MenuItem>
      </Menu>
    </DemoLayout>
  );
}

Disabled #

MenuItems can be disabled. Render a disabled MenuItem to let your user know that the option is available under the right conditions.

For example, you would disable "Open Recent" if there are no recent files available, yet you want the user to know that feature is available under other conditions.

New File

Open

Open Recent

Save

<DemoLayout>
  <Menu>
    <MenuItem>New File</MenuItem>
    <MenuItem>Open</MenuItem>
    <MenuItem disabled onClick={() => console.log('onClick is not triggered for disabled MenuItems')}>
      Open Recent
    </MenuItem>
    <MenuItem>Save</MenuItem>
  </Menu>
</DemoLayout>

Bidirectionality #

MenuItems with Icons are reversed when the direction theme variable is set to rtl (right-to-left). A subset of Icons that convey directionality will be reversed.

نص عنصر القائمة

نص عنصر القائمةنص ثانوي

رمز البدء

رمز النهاية

<DemoLayout dir="rtl">
  <ThemeProvider theme={{ direction: 'rtl' }}>
    <Menu>
      <MenuItem>نص عنصر القائمة</MenuItem>
      <MenuItem secondaryText="نص ثانوي">نص عنصر القائمة</MenuItem>
      <MenuItem iconStart={<IconHelp />}>رمز البدء</MenuItem>
      <MenuItem iconEnd={<IconHelp />}>رمز النهاية</MenuItem>
    </Menu>
  </ThemeProvider>
</DemoLayout>

API & Theme #

MenuItem Props #

The MenuItem component takes the following React props.

Name	Type	Description
children	React$Node	Rendered content of the component
disabled	boolean	Disable the menu item
iconEnd	React$Element<*>	Icon that goes after the childre
iconStart	React$Element<*>	Icon that goes before the children
index	number	Item index - provided to render callback
isHighlighted	boolean	Display the item in an active style
item	MenuItem	Item data - provided to render callback
onClick		Called with the click event
render		Provides custom rendering control. See the custom item example and our render props guide.
secondaryText	React$Node	Secondary text
variant	'danger' \| 'success' \| 'warning'	Available variants

Undocumented properties, including as and css, will be applied to the root element.

MenuItem Theme Variables #

These variables can be used as hooks to override this component's style at either a local or global level. The theme referenced below is whatever theme is available from props to the instance of this component.

Variable	Value
MenuItem_backgroundColor_selected	theme.backgroundColor_theme_selected
MenuItem_backgroundColor_active	theme.color_gray_20
MenuItem_backgroundColor_focus	theme.color_gray_10
MenuItem_backgroundColor_hover	theme.color_gray_10
MenuItem_backgroundColor_selectedActive	theme.backgroundColor_theme_selectedActive
MenuItem_backgroundColor_selectedHover	theme.backgroundColor_theme_selectedHover
MenuItem_color	theme.color
MenuItem_fontWeight	theme.fontWeight_regular
MenuItem_fontWeight_selected	theme.fontWeight_bold
MenuItem_paddingHorizontal	theme.space_inset_md
MenuItem_paddingVertical	theme.space_inset_sm
MenuItemContent_fontSize	theme.fontSize_ui
MenuItemIcon_color	theme.icon_color_theme
MenuItemIcon_margin	theme.space_inset_sm
MenuItemSecondaryText_color	theme.color_mouse
MenuItemSecondaryText_fontSize	theme.fontSize_mouse

Usage #

When/How to Use #

Use MenuItems to present the user with a choice of actions, and don't use MenuItems to display content that is not actionable. For example, don't create a Menu with several options where the last item is an un-clickable status message showing the number of available servers. This information is not actionable and perhaps belongs somewhere else in your interface.

Use the secondary text to give hints about extra functionality or provide status.

Best Practices #

Use the appropriate variant to give your users hints about what the potential outcome of an action will be.

Start instance

Generate snapshot

Reboot instance

Terminate instance

Don't use a variant that differs from intent, as this will cause confusion.

Clone table

Create new table

Clearly label MenuItem actions to be predictable for frictionless interaction. Labels should be structured: <verb> <noun>.

Select line⌘L

Select word⌃⇧W

Join lines⌘J

Don't use vague labels. Users should know exactly what will happen when they click a Button.

Various config options

Do it

Use the secondaryText attribute to give hints about extra functionality or provide status context.

Cut⌘X

Copy⌘C

Paste⌘V

Don't display non-action labels in a MenuItem. All MenuItems in a Menu should be actionable. If an option only exists to provide information, it probably belongs somewhere else.

Daily revenue - $6543

Initiate full refund

Initiate partial refund

Email customer

Don't use disabled MenuItems as section titles. Instead, use the title prop of a MenuGroup to show meta information for a group, or place this information elsewhere in the interface.

Instance Id: 12345

Start instance

Generate snapshot

Reboot instance

Terminate instance