ListMenu

A vertical list of items with optional search and creation actions. Supports both single and multi-select.

It is important to note that this component only describes the menu itself, but not the trigger. You will rarely have to use this component directly.

Components that use ListMenu and provide a trigger include SelectBox, MultiSelectBox, and ActionMenu.

  1. Search inputFor filtering options
  2. Group titleDesignates an items group
  3. Items groupGroups multiple options
  4. Group separatorSeparates each items group
  5. Active indicatorFor single-select only
  6. Create actionButton for creating new item
  7. CheckboxFor multi-select only
Figma SVG of the ListMenu with numbers referring to the below items.

Best practices

When to use

  • When you need to display a list of options that is shown based on a trigger (e.g. a button click, a select box, etc.).
  • When you need the user to select one or more options from a list.
  • If the items are static (i.e. user's can't add to them), you should have at least five options to select from.
  • An exception can be made if there is not much available space.
  • If users can add to the list of options.

When NOT to use

  • When you have less than five static options and no space constraints. In this case, it's better to use checkboxes (for multi-select) or radio controls (for single-select).
  • Note: five options is not an absolute rule, but rather a general guidance. If you find that this number might differ a bit in the context of your design, it is ok to fluctuate a bit on this number.
  • When you need all options to be always visible.

Layout

  • ListMenus are always placed outside of the flow of the document and are absolutely position relative to their trigger.
  • ListMenus should never overflow the viewport. If their default placement would place them partially or completely outside of the viewport, they should be repositioned to be completely within the viewport.

Content

  • Keep options short and concise.

Accessibility

  • Users can navigate through the options using the keyboard.

Variants

Entire ListMenu

Show filter

Shows the next input used to filter the options.

  • false
  • true

Show action

Shows the action at the bottom of the list. Can be either a creation or deletion action.

  • false
  • true

Grouping

Determines whether the items are grouped or ungrouped. Each group has a heading label.

  • ungrouped
  • grouped

Individual ListMenu items

Selected

Shows an item as selected or not. For single select lists, this shows as a dark indicator next to the label. For multi-select lists, this shows as a checked checkbox.

  • false
  • true

Show icon

Shows an icon next to the label.

  • false
  • true

Show flag

Shows a flag next to the label.

  • false
  • true

Show badge

Shows a badge next to the label.

  • false
  • true

Show description

Shows a description underneath the label.

  • false
  • true

Show add-on

Shows a text anchored to the right of an individual item. This text is formatted similarly to the description.

  • false
  • true

Guidelines

Visibility and placement

Always keep it hidden by default and only show it through interaction with a trigger

The SelectBox, for example, includes a trigger that, when clicked, opens the ListMenu.

Don't keep it always open not include it within the layout

In this example, a ListMenu has been added to the page's body as an alternative to a RadioSet.

Consistent icon configuration

Use the same configuration for all options, even across different groupings

Don't use different configurations

This will make the list difficult to parse, as items will not align to each other and the visual rhythm will be lost.

Sorting

Sort items logically (e.g. alphabetically)

Consider the most appropriate sorting for each case.

Don't just randomly place items

This will make the list difficult to parse, as items will not align to each other and the visual rhythm will be lost.

Filtering

If there are more than 10 items, include a filter input.

Use either icons or flags. Not both.

Don't use flags and icons together.

Behaviors

States

Empty

  • The control shows an empty message when there are no options.

Too many results

  • There is no upper limit on the number of items allowed in a ListMenu, but the list will be cropped and scroll enabled when it exceeds the height of the control.

Disabled

  • Disabled triggers should not open the ListMenu when they are disabled.
  • ListMenu can also disable individual list items. The entire item will be made lighter and will not respond to interactions.

Focused

  • Focused items will be highlighted with the hover style.

Hovered

  • When hovered, an item will display a subtle gray background.

Active

  • Active items will be identified by the active indicator (on single-select ListMenus) or a checked checkbox (on multi-select).