Overflow menu

Overflow menu in Storybook

Usage

Overview

The overflow menu indicates there is more available content in a UI object than can be displayed at once. Additional lists, options and functionality can be hidden in an expandable menu so as not to clutter the main interface.

Anatomy

• A. Overflow menu in a table.
• B. Overflow menu in a top nav.

The overflow menu is indicated with an ellipsis icon. It appears at the (right-hand) end of a row of navigation titles or on a content row.

A. Overflow menu (Table):

1. Ellipsis icon: The table overflow menu is indicated with an ellipsis icon which always appears on the right-hand side of a table row.
2. Dropdown menu: The overflow menu consists of a list of additional interactions, e.g., tools/actions, e.g., delete, edit, duplicate (duplicate row).
3. Dropdown menu shadow: A shadow is used as part of the overflow menu to clearly distinguish it from the background it's set against.
4. Tools/actions icons: Iconography can be added to the overflow menu list items, providing a quick and clear indication of the associated functionality.
5. Tools labels: Overflow menu list items are labeled according to the Jutro dropdown menu guidelines.

B. Overflow menu (Top nav):

1. Ellipsis icon: The top navigation overflow menu is indicated with an ellipsis icon which always appears on the right-hand side of a top nav strip.
2. Dropdown menu: The overflow menu consists of a list of additional top navigation links.
3. Dropdown menu shadow: A shadow is used as part of the overflow menu to clearly distinguish it from the background it's set against.

Best practices

• Always position the overflow menu (ellipsis) icon to the end of an object, (when start / end is left / right it will be on the right-hand side), to indicate additional content/functionality.
• Use overflow menus to maintain clean user interfaces by hiding the secondary options in an expandable menu, or alternatively, to show the important actions in terms of engagement.
• Make sure you include only those actions that are necessary to complete priority tasks and are contextually relevant and list them in order of frequency of use.
• Use overflow menus to contain additional menu items or actions as they are incrementally/progressively added to the UI.
• Do not use cascading menus.
• Disable options that are not relevant in a given context.

Interactions

Mouse

• An overflow menu ellipsis symbol is highlighted when hovered, indicating interactivity.
• An overflow menu (ellipsis) symbol may be invisible until an associated object is hovered or clicked, for example, a table row, which helps draw attention to the inclusion of the overflow menu object and functionality.
• Clicking on the overflow menu ellipsis symbol will produce a dropdown menu of content, by clicking off the menu anywhere the menu will disappear
• Overflow menu items will appear highlighted with a blue background when hovered over; a single mouse click will trigger the action or link from the menu.

Keyboard

The component is actionable through the Spacebar and Enter keys.

Screen reader

The overflow menu component is part of the navigation menu and as such includes the role of "menuitem'. The WAI-ARIA role of aria-expanded="false' indicate that its default state is collapsed with extra content contained within it. This value toggles to true when the overflow menu is expanded.

UX writing considerations

• Text within an overflow menu should be direct and concise so that users can quickly decide on an action.
• For actions that could cause a significant change to users' data, consider using a horizontal rule to separate that action and list it below the primary set of actions.

Accessibility

The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.1 AA requirements. Non-textual content that needs to convey meaning (such as icons and keyboard focus visibility) has a contrast ratio of at least 3:1 with its adjacent colors. All content is visible and functional up to and including 400% without requiring scrolling in two dimensions.

This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance.

Code

<DropdownMenu
  id="dropdown-menu"
  dropUp={true}
  renderTrigger={(
    {
      id,
      menuId,
      ref,
      'aria-haspopup': ariaHasPopup,
      'aria-expanded': ariaExpanded,
      title = 'Menu',
      onKeyDown,
    },
    toggleMenu
  ) => {
    return (
      <Button
        id={id}
        ref={ref}
        aria-expanded={ariaExpanded}
        aria-controls={menuId}
        aria-haspopup={ariaHasPopup}
        onClick={() => toggleMenu()}
        onKeyDown={onKeyDown}
        label={title}
      />
    );
  }}>
  <DropdownMenuLink>First menu item</DropdownMenuLink>
  <DropdownMenuLink>Second menu item</DropdownMenuLink>
  <DropdownMenuLink>Third menu item</DropdownMenuLink>
</DropdownMenu>

Import statement

import {
  DropdownMenuHeader,
  DropdownMenu,
  DropdownMenuSeparator,
} from '@jutro/components';
import { DropdownMenuLink } from '@jutro/router';

Component contract

Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.

Properties

idrequired

Type

string

Description

Unique identifier for the component.

alignRight

Type

boolean

Description

If set to true, the items are aligned to the right edge of the menu.

autoFocus

Type

boolean

Description

If set to true, the first menu item gets focused after opening the dropdown menu.

Default value

true

className

Type

string

Description

CSS class name for this component.

dropUp

Type

boolean

Description

If set to true, the menu appears above the trigger component.

focused

Type

boolean

Description

If set to true, the root element is considered the currently active element.

isOpen

Type

boolean

Description

Controls whether the container is hidden.

keepContext

Type

boolean

Description

If set to true, sets the title of the selected value to be the same as the selected item text.

menuClassName

Type

string

Description

Override the class for the inner menu of the dropdown menu.

onMenuClose

Type

() => void

Description

Callback that's supposed to be triggered when menu gets closed.

onMenuOpen

Type

() => void

Description

Callback that's supposed to be triggered when menu gets closed.

openMenuId

Type

string

Description

Id of the component instance that's supposed be to currently opened. Mostly useful when rendering multiple instances next to each other.

popperOptions

Type

{isOpen, triggerElement, children, placement, popperOptions, onClose, noPortal, portalTargetElement}

childrenrequired

Type

React.ReactNode

Description

Node to be rendered inside the expanded menu.

isOpenrequired

Type

boolean

Description

Controls whether the container is hidden.

noPortal

Type

boolean

Description

If true, Popper will not be rendered inside React Portal.

onClose

Type

() => void

Description

Optional callback that is triggered when container is closed.

placement

Type

'auto' | 'auto-end' | 'auto-start' | 'bottom' | 'bottom-end' | 'bottom-start' | left' | left-end' | 'left-start' | 'right' | 'right-end' | 'right-start' | 'top' | 'top-end' | 'top-start'

Description

Override the menu position.

popperOptions

Type

Options

Description

Additional options passed as third argument to usePopper hook.

portalTargetElement

Type

HTMLElement

Description

React Portal target element, preferably one of the top-level DOM elements. Must be unique, defaults to body element.

triggerElement

Type

Element

Description

Reference element to position the menu.

Description

Additional options passed as third argument to usePopper hook.

renderTrigger

Type

(props, togglemenu) => ReactElement

Function return value

Type

ReactElement

Description

The function must return a React Element that represents the trigger element for the menu, for example a Button as used in the examples. The trigger element must take at least three arguments: an object of props for the component; an onClick callback function; and a Boolean variable to control the state of visibility, like isVisible.

props

Type

DropdownMenuTriggerProps & CustomProp

'aria-expanded'

Type

boolean

Description

A label for use by assistive technology.

'aria-haspopup'

Type

boolean

Description

A label for use by assistive technology.

'aria-label'

Type

string

Description

A label for use by assistive technology.

id

Type

string

Description

Unique identifier for the component.

isOpen

Type

boolean

Description

Controls whether the container is hidden.

menuId

Type

string

Description

The id of the DropdownMenu component the renderTrigger is associated with.

onKeyDown

Type

function (React.KeyboardEvent<HTMLInputElement>)

Description

Callback invoked to take when a user presses any key.

ref

Type

MutableRefObject<HTMLButtonElement>

Description

A reference to the element that is clicked on to open and close the DropDownMenu component.

title

Type

string

Description

A label for the render trigger.

Description

Props to pass to the render trigger element. The CustomProps type depends on what other components might be wrapping DropdownMenu. The DropdownMenuTriggerProps are defined in the 'Show object details' section.

toggleMenu

Type

(open?: boolean) => void

Description

Function that runs when menu is opened or closed. The function has an optional argument named open that is a boolean which is true if the menu is being opened.

Description

Props to pass to the render trigger element. The CustomProps type depends on what other components might be wrapping DropdownMenu. The DropdownMenuTriggerProps are defined in the 'Show object details' section.

triggerAriaLabel

Type

IntlMessageShape

Description

Aria label for the trigger button.

Dropdown menu child properties

DropdownMenu components use DropdownMenuHeader, DropdownMenuLink and DropdownMenuSeparator as child components. The properties for these components are as follows:

DropdownMenuHeader properties

children

Type

React.ReactNode

Description

The component children, wrapped by the dropdown menu header component.

id

Type

string

Description

Unique identifier for the component.

title

Type

React.ReactNode | IntlMessageShape

Description

The element node representing the header title, in most cases it will be a plain string.

DropdownMenuLink properties

activeClassName

Type

string

Description

The class to give the link when it is active.

children

Type

string

Description

The children elements to render inside of the DropdownMenuLink.

className

Type

string

Description

CSS class name for this component.

disabled

Type

boolean

Description

If set to true, this link is disabled.

focused

Type

string

Description

If set to true, the link is considered as the currently active one.

href

Type

IntlMessageShape

Description

Used to specify an external link.

icon

Type

string | Icon

Description

An Icon component to render on the component. The value must be an Icon component or the icon's name. For example, CheckIcon or 'gw-check'.

iconClassName

Type

string

Description

Additional class names for the icon.

iconPosition

Type

'left' | 'right'

Description

Where the icon is placed relative to the text.

id

Type

string

Description

Unique identifier for the component.

onClick

Type

function (React.MouseEvent<HTMLElement>)

Description

On click event handler.

rel

Type

string

Description

Specifies the relationship between the current and an external document, like the HTML rel attribute.

target

Type

string

Description

Specifies where to open the external link, like the HTML target attribute.

to

Type

IntlMessageShape | {pathname?, hash?}

hash

Type

IntlMessageShape

Description

Hash to put in the URL.

pathname

Type

IntlMessageShape

Description

Link path.

Description

Used to specify an internal link.

visible

Type

boolean

Description

If set to true, this link is visible.

DropdownMenuSeparator properties

className

Type

string

Description

CSS class name for this component.

id

Type

string

Description

Unique identifier for the component.

Hooks

No hooks are available for DropdownMenu.

Translation keys

There are no translations for DropdownMenu.

For information on how to manage translations, see our section about Internationalization.

Escape hatches

For more information, see our documentation about escape hatches.

Examples

Overflow menus are rendered using the DropdownMenu component. The renderTrigger property determines the component the DropdownMenu is rendered as.

When the user activates the component, it renders a tree of any of the following:

• DropdownMenuLink
• DropdownMenuSeparator
• DropdownMenuHeader

Check out the Usage section for details about how to design an overflow menu properly, and the different configuration options we provide.

Basic overflow menu example

The following example demonstrates how to create a simple DropdownMenu component. The renderTrigger property defines a button which opens the menu when clicked.

<DropdownMenu
  id="dropdown-menu"
  renderTrigger={(
    {
      id,
      menuId,
      ref,
      'aria-haspopup': ariaHasPopup,
      'aria-expanded': ariaExpanded,
      title = 'Menu',
      onKeyDown,
    },
    toggleMenu
  ) => {
    return (
      <Button
        id={id}
        ref={ref}
        aria-expanded={ariaExpanded}
        aria-controls={menuId}
        aria-haspopup={ariaHasPopup}
        onClick={() => toggleMenu()}
        onKeyDown={onKeyDown}
        label={title}
      />
    );
  }}>
  <DropdownMenuLink>First menu item</DropdownMenuLink>
  <DropdownMenuLink>Second menu item</DropdownMenuLink>
  <DropdownMenuLink>Third menu item</DropdownMenuLink>
</DropdownMenu>

Headers and separator example

You can use headers and separators to create separation between groups of options.

<DropdownMenu
  id="dropdown-menu"
  renderTrigger={(
    {
      id,
      menuId,
      ref,
      'aria-haspopup': ariaHasPopup,
      'aria-expanded': ariaExpanded,
      title = 'Menu',
      onKeyDown,
    },
    toggleMenu
  ) => {
    return (
      <Button
        id={id}
        ref={ref}
        aria-expanded={ariaExpanded}
        aria-controls={menuId}
        aria-haspopup={ariaHasPopup}
        onClick={() => toggleMenu()}
        onKeyDown={onKeyDown}
        label={title}
      />
    );
  }}>
  <DropdownMenuLink>First menu item</DropdownMenuLink>
  <DropdownMenuLink>Second menu item</DropdownMenuLink>
  <DropdownMenuSeparator />
  <DropdownMenuLink>Separated menu item</DropdownMenuLink>
  <DropdownMenuSeparator />
  <DropdownMenuHeader title="Header text">
    <DropdownMenuLink>First header menu item</DropdownMenuLink>
    <DropdownMenuLink>Second header menu item</DropdownMenuLink>
  </DropdownMenuHeader>
</DropdownMenu>

Drop up example

You can use the dropUp property to render the menu above the button when clicked.

<DropdownMenu
  id="dropdown-menu"
  dropUp={true}
  renderTrigger={(
    {
      id,
      menuId,
      ref,
      'aria-haspopup': ariaHasPopup,
      'aria-expanded': ariaExpanded,
      title = 'Menu',
      onKeyDown,
    },
    toggleMenu
  ) => {
    return (
      <Button
        id={id}
        ref={ref}
        aria-expanded={ariaExpanded}
        aria-controls={menuId}
        aria-haspopup={ariaHasPopup}
        onClick={() => toggleMenu()}
        onKeyDown={onKeyDown}
        label={title}
      />
    );
  }}>
  <DropdownMenuLink>First menu item</DropdownMenuLink>
  <DropdownMenuLink>Second menu item</DropdownMenuLink>
  <DropdownMenuLink>Third menu item</DropdownMenuLink>
</DropdownMenu>

Changelog