Dropdown menu
A dropdown menu displays a list of actions or options to a user.Neutral selected states
When the platform-dst-tokens-finesse feature flag is enabled, this component uses the new neutral treatment for selected states.
Motion in Early Access
Motion updates for this component are in Early Access and available behind the platform-dst-motion-uplift-popup feature flag.
Appearance
Default
Use default for the default dropdown menu appearance. The default menu will scroll after its
height exceeds the pre-defined amount.
Density
Configure the density of the dropdown with the spacing prop. By default the spacing is cozy, but
you can also apply compact depending on your use case.
Tall
Use tall to control the height of the menu. The tall menu will not scroll until the height exceeds
the height of the viewport.
Custom triggers
There are three recommended ways to customize a trigger.
Using trigger
Set trigger to a custom react component which accepts the provided props.
Use the trigger prop and pass in an html element.
Use the trigger prop and pass in a string.
You can nest dropdown menus inside other dropdown menus.
However, be mindful that nested menus quickly become confusing, inaccessible, and difficult to navigate. We recommend limiting nesting to two layers only.
States
Loading
If isLoading is true, a spinner is rendered instead of the dropdown items.
Open
Use isOpen to control the open state of the dropdown menu.
Positioning
Default placement
By default, the dropdown menu will be placed next to your trigger.
Placement
Use placement to set the menu placement to the bottom end, for example.
Should flip
If it doesn't fit in the viewport, use shouldFlip to place to the dropdown menu on the opposite
side of its trigger.
Z-index
Use zIndex to resolve clashes with other layered components with competing z-index values, such as
popup.
Content without portal
By default, the dropdown menu content is rendered inside React.Portal. Use shouldRenderToParent
prop to render the content directly after the trigger element.
Use shouldFitContainer to fit the dropdown menu width to its parent's width. When set to true,
the trigger and dropdown menu elements will be wrapped in a div with position: relative. The
dropdown menu will be rendered as a sibling to the trigger element, and will be full width.
Accessibility
Accessible trigger labels
Sometimes multiple instances of a dropdown menu with the same visible label are required. In order
to provide more context to assistive technologies, you can specify a unique aria-label for each
unique menu.
When providing the aria-label along with a visible label, make sure that the first few words of
the aria-label match the visible label. This is to support Voice Input users that use the visible
label to interact with controls.
Accessible group labels
If multiple dropdown item groups are used, a title should be provided for the user to understand
the menu's structure.
import React from 'react';
import DropdownMenu from '@atlaskit/dropdown-menu/dropdown-menu';
import DropdownItem from '@atlaskit/dropdown-menu/dropdown-menu-item';
import DropdownItemGroup from '@atlaskit/dropdown-menu/dropdown-menu-item-group';
const DropdownItemGroupTitleExample = (): React.JSX.Element => {
return (
<DropdownMenu trigger="Page actions" shouldRenderToParent>
<DropdownItemGroup title="Edit page">
<DropdownItem>Edit</DropdownItem>
<DropdownItem>Move</DropdownItem>
<DropdownItem>Clone</DropdownItem>
</DropdownItemGroup>
<DropdownItemGroup title="Tools">
<DropdownItem>Integrations</DropdownItem>
<DropdownItem>Permissions</DropdownItem>
</DropdownItemGroup>
</DropdownMenu>
);
};
export default DropdownItemGroupTitleExample;