Menu

A menu gives access to menu items, through a panel that opens from a trigger element. Menu items usually trigger actions.

Demo

Usage

When to use

• Show more options in a limited space. Use a menu to show more options and actions when there's limited space.

When not to use

• Choosing options in a form. Use a Select to choose from a set of options as part of a form.

Format

Content

Label

• Menu item labels should be short and easy to understand.
• One or two words is often enough to explain the action.
• Refer to the writing guidelines and glossary for more information about writing useful labels.

Order and grouping

Demo

<FlyoutMenu>
    <MenuSectionHeader label="Section with sub-menus" />
    <MenuItem label="Item 1" />
    <MenuItem label="Item 2">
        <MenuItem label="Item 2 a" />
        <MenuItem label="Item 2 b">
            <MenuItem label="Item 2 b i" />
            <MenuItem label="Item 2 b ii" />
        </MenuItem>
        <MenuItem label="Item 2 c" />
    </MenuItem>
    <MenuItem label="Item 3" />
    <MenuItem label="Item 4">
        <MenuItem label="Item 4 a" />
        <MenuItem label="Item 4 b">
            <MenuItem label="Item 4 b i" />
            <MenuItem label="Item 4 b ii" />
        </MenuItem>
        <MenuItem label="Item 4 c" />
    </MenuItem>
    <MenuItem label="Item 5" />
    <MenuSectionHeader label="Section with dividers between menu items" />
    <MenuItem label="Item 1" />
    <MenuDivider />
    <MenuItem label="Item 2" />
    <MenuDivider />
    <MenuItem label="Item 3" />
</FlyoutMenu>

• Order the menu items in a logical way, grouping together related actions.
• Destructive menu items should be shown in their own group, usually last.

Size

Demo

<FlyoutMenu>
    <MenuItem dense label="Menu item label" />
    <MenuItem dense label="Menu item label" />
</FlyoutMenu>

• Menu items are available in two sizes, regular and dense.
• Use dense sized menu items in complex, information-dense layouts. Otherwise, the regular size.

Nesting

As shown in the order and grouping section, a menu can contain multiple levels of menu items.

<FlyoutMenu>
    <MenuItem label="Menu item label">
        <MenuItem label="Menu item label" />
    </MenuItem>
</FlyoutMenu>

• A menu item can open another menu.
• Use nested menus when there's complex options that can be grouped together, like a Download parent item containing different file formats.
• Avoid nesting more than 3 levels of menus.

Options

Dividers and section headers

As shown in the order and grouping section, a menu can contain dividers and section headers.

<FlyoutMenu>
    <MenuSectionHeader label="Actions" />
    <MenuItem label="Add to program" />
    <MenuItem label="Add to stage" />
    <MenuSectionHeader label="Other" />
    <MenuItem label="Analyze data" />
    <MenuItem label="Run integrity check" />
</FlyoutMenu>

• A menu can show dividers between groups of menu items.
• Use dividers to split items that logically belong together. This makes the menu easier to scan.
• Dividers can also show a section header, a text label for that group of menu items.
• Use a section header to clarify what the menu items refer to, but don't rely on it. Menus and menu item actions should be clear without needing section headers.

Suffix

Demo

<FlyoutMenu>
    <MenuItem
        suffix={<IconReference />}
        icon={<IconReference />}
        label="Open in data visualizer"
    />
</FlyoutMenu>

• A menu item can show a suffix.
• Use a suffix to show extra information about the context or intent of a menu item.
• Common use cases include showing a menu item's keyboard shortcut and showing an indicator that a menu item will open a new tab.
• Don't include interactive components, like buttons, in a menu item suffix.

Icon

Demo

<Menu>
    <MenuItem icon={<IconApps24 />} label="Menu item" />
    <MenuItem
        icon={<IconApps24 color="magenta" />}
        label="Menu item - with custom icon fill"
    />
</Menu>

• A menu item can show an icon.
• Use icons to support the text label by providing context or a visual reference.
• Don't include icons for decoration only, they add complexity to the interface.

Type: Destructive

Demo

<MenuItem destructive label="Delete program" />

• Use destructive menu items for critical, destructive actions like Delete or End process.
• Don't use a destructive menu item unless the item is both critical and destructive. Important menu items shouldn't use the destructive type to highlight only their importance.
• Most menus should have a maximum of one destructive item.
• Use a divider to separate the destructive menu item from the other menu items. A section header usually isn't necessary.

State: Disabled

Demo

<MenuItem disabled label="Save" />

• Use disabled menu items when a menu item is temporarily unavailable.
• Don't use the disabled state if the menu item will never be available in this context. Remove it instead.

API Reference

FlyoutMenu

Usage

To use FlyoutMenu, you can import the component from the @dhis2/ui library

import { FlyoutMenu } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
children	node			Typically, but not limited to, MenuItem components
className	string
closeMenu	function			when Escape key is pressed, this function is called to close the flyout menu
dataTest	string	'dhis2-uicore-menu'
dense	boolean			Menu uses smaller dimensions
maxHeight	string	'auto'
maxWidth	string	'380px'

Menu

Usage

To use Menu, you can import the component from the @dhis2/ui library

import { Menu } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
children	node			Typically MenuItem, MenuDivider, and MenuSectionHeader
className	string
dataTest	string	'dhis2-uicore-menulist'
dense	boolean			Applies dense property to all child components unless already specified

MenuDivider

Usage

To use MenuDivider, you can import the component from the @dhis2/ui library

import { MenuDivider } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
className	string
dataTest	string	'dhis2-uicore-menudivider'
dense	boolean

MenuItem

Usage

To use MenuItem, you can import the component from the @dhis2/ui library

import { MenuItem } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
active	boolean
ariaLabel	string			By default, the label prop is used for the aria-label attribute on the underlying HTML element. If this prop is defined, it will be used as the aria-label instead
checkbox	boolean
checked	boolean
chevron	boolean
children	node			Nested menu items can become submenus. See showSubMenu and toggleSubMenu props, and 'Children' demo
className	string
dataTest	string	'dhis2-uicore-menuitem'
dense	boolean
destructive	boolean
disabled	boolean
href	string			For using menu item as a link
icon	node			An icon for the left side of the menu item
label	node			Text in the menu item. If it's a string, will be used as aria-label
showSubMenu	boolean			When true, nested menu items are shown in a Popper
suffix	node			A supporting element shown at the end of the menu item
tabIndex	number
target	string			For using menu item as a link
toggleSubMenu	function			On click, this function is called (without args)
value	string			Value associated with item. Passed as an argument to onClick handler.
onClick	function			Click handler called with signature ({ value: string }, event)

MenuSectionHeader

Usage

To use MenuSectionHeader, you can import the component from the @dhis2/ui library

import { MenuSectionHeader } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
className	string
dataTest	string	'dhis2-uicore-menusectionheader'
dense	boolean
hideDivider	boolean
label	node