Dropdown displays a list of actions, options or links. It is triggered when a user interacts with a Button, Textfield or other control. Dropdown allows for complex functionality that can’t be accomplished with SelectList.
also known as Menu, Contextual Menu
Remember to include the following ARIA attributes on the element used for the
accessibilityControls: lets the screen reader know that this element controls the Dropdown menu (should match the
idproperty passed to Dropdown). Populates the aria-controls attribute.
accessibilityHaspopup: lets the screen reader know that there is a Dropdown menu linked to the trigger. Populates the aria-haspopup attribute.
accessibilityExpanded: informs the screen reader whether the Dropdown menu is currently open or closed. Populates the aria-expanded attribute.
Spacekey on the Dropdown's trigger opens the menu
Escapekey closes the menu, while moving focus back on the Dropdown's trigger
- Arrow keys are used to navigate items within the menu
Enterkey selects an item within the Menu
Shift + Tabclose the menu and move focus accordingly
When the text of the Dropdown.Item becomes longer than the width of the menu, either intentionally or through localization, the text will truncate at one line. Subtext will wrap as needed to display the full text.
Use Dropdown.Item for action & selection, when the Dropdown item triggers an action or selects an option.
Use Dropdown.Link for navigation, when the Dropdown item navigates to a new page.
Use Dropdown.Section to create hierarchy within a single Dropdown.
Types of items
Typically a Dropdown item triggers an action, like “Hide a Pin”, or makes a selection, like “Cozy” for a layout setting. Use Dropdown.Item for these use cases.
onSelect handles the user interaction, with the optional
selected indicating the currently-selected item.
If an item navigates to a new page, use Dropdown.Link with the required
href prop. If the item navigates to a page outside of the current context, (either a non-Pinterest site or a different Pinterest sub-site), the
isExternal prop should also be specified to display the "up-right" icon. Optional additional actions to be taken on navigation are handled by
onClick. Dropdown.Link can be paired with OnLinkNavigationProvider. See OnLinkNavigationProvider to learn more about link navigation.
Dropdown can also be composed of Dropdown.Section(s), which simply require a label. Use Dropdown.Section(s) to create hierarchy within a single Dropdown. Dropdown.Sections, Dropdown.Items and Dropdown.Links can be mixed as needed.
Dropdown can also contain a custom header by specifying
headerContent, which always appears at the very top of the menu. It can be used instead of a section header if the menu contains only one type of content that needs additional description. It can contain anything, but most often will contain just text and/or a link.
Each Dropdown item can also contain
subtext below the label. This
subtext will wrap if needed. Use this text to add an additional description of the Dropdown item.
Custom item content
If needed, users can supply custom content to each Dropdown.Item or Dropdown.Link. This can be useful when extra functionality is needed. However, please use with caution and only when absolutely necessary.
To ensure the entire width of the item is clickable, you will likely need to surround your custom content with a full-width Box.
Under the hood, Dropdown executes two actions: recognizing subcomponents by display name and sequencially indexing each subcomponent for keyboard navigation.
Dropdown requires its own subcomponents as children to build the list of actions.
When building a Dropdown, we might want to render different combinations of subcomponents conditionally. Dropdown supports simple conditional rendering of subcomponents lists wrapped in React.Fragment as well as consecutive arrays of subcomponent arrays. See the example below which illustrates both of these cases. More logic complexity might break the correct Dropdown behavior.
Component quality checklist
Component is not currently available in Figma.
Component is available in code for web and mobile web.
Component is not currently available in code for iOS.
Component is not currently available in code for Android.
ScrollableContainer is needed for proper positioning when the Dropdown is located within a scrolling container. The use of ScrollableContainer ensures the Dropdown remains attached to its anchor when scrolling.
If users need to select from a short, simple list (without needing sections, subtext details, or the ability to filter the list), use SelectList.
If users need the ability to choose an option by typing in an input and filtering a long list of options, use ComboBox.
OnLinkNavigationProvider allows external link navigation control across all children components with link behavior.