Automattic Design System

Components

Dropdown

Renders a button that opens a floating content modal when clicked.

import { Dropdown } from '@wordpress/components';

View on Storybook

View in Figma

View source on GitHub

PropsPermalink to this section

NameDefaultDescription
className

string

The className of the global container.

contentClassName

string

If you want to target the dropdown menu for styling purposes, you need to provide a contentClassName because it’s not being rendered as a child of the container node.

expandOnMobilefalse

boolean

Opt-in prop to show popovers fullscreen on mobile.

focusOnMount'firstElement'

Mode | undefined

Determines focus behavior when the dialog mounts.

  • "firstElement" focuses the first tabbable element within.
  • "firstInputElement" focuses the first value control within.
  • true focuses the element itself.
  • false does nothing and should not be used unless an accessible substitute behavior is implemented.
headerTitle

string

Set this to customize the text that is shown in the dropdown’s header when it is fullscreen on mobile.

onClose

() => void

A callback invoked when the popover should be closed.

onToggle

(willOpen: boolean) => void

A callback invoked when the state of the dropdown changes from open to closed and vice versa.

popoverProps

Omit<ComponentPropsWithoutRef<{ (props: WordPressComponentProps<Omit<WordPressComponentProps<PopoverProps, "div", false>, "onDrag" | "onDragEnd" | "onDragStart" | "onAnimationStart" | ... 53 more ... | "ignoreStrict"> & RefAttributes<...>, ElementType<...> | null, boolean>): ReactNode; displayName?: string | undefin...

Properties of popoverProps object will be passed as props to the Popover component. Use this object to access properties/features of the Popover component that are not already exposed in the Dropdown component, e.g.: the ability to have the popover without an arrow.

renderContent Required

(props: CallbackProps) => ReactNode

A callback invoked to render the content of the dropdown menu. Its first argument is the same as the renderToggle prop.

renderToggle Required

(props: CallbackProps) => ReactNode

A callback invoked to render the Dropdown Toggle Button.

The first argument of the callback is an object containing the following properties:

  • isOpen: whether the dropdown menu is opened or not
  • onToggle: A function switching the dropdown menu’s state from open to closed and vice versa
  • onClose: A function that closes the menu if invoked
style

CSSProperties

The style of the global container.

position

"top" | "middle" | "bottom" | "top center" | "top left" | "top right" | "middle center" | "middle left" | "middle right" | "bottom center" | "bottom left" | "bottom right" | "top center left" | "top center right" | "top center top" | "top center bottom" | "top left left" | "top left right" | "top left top" | "top left bottom" | "top right left" | "top right right" | "top right top" | "top right bottom" | "middle center left" | "middle center right" | "middle center top" | "middle center bottom" | "middle left left" | "middle left right" | "middle left top" | "middle left bottom" | "middle right left" | "middle right right" | "middle right top" | "middle right bottom" | "bottom center left" | "bottom center right" | "bottom center top" | "bottom center bottom" | "bottom left left" | "bottom left right" | "bottom left top" | "bottom left bottom" | "bottom right left" | "bottom right right" | "bottom right top" | "bottom right bottom"

Legacy way to specify the popover’s position with respect to its anchor. For details about the possible values, see the Popover component’s docs. Note: this prop is deprecated. Use the popoverProps.placement prop instead.

open

boolean

The controlled open state of the dropdown. Must be used in conjunction with onToggle.

defaultOpen

boolean

The open state of the dropdown when initially rendered. Use when you do not need to control its open state. It will be overridden by the open prop if it is specified on the component’s first render.

as

"symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | "canvas" | ... 164 more ... | undefined

The HTML element or React component to render the component as.

ExamplesPermalink to this section

DefaultPermalink to this section

const Default = () => <Dropdown
    onClose={fn()}
    onToggle={fn()}
    renderToggle={( { isOpen, onToggle } ) => (
        <Button
            __next40pxDefaultSize
            onClick={ onToggle }
            aria-expanded={ isOpen }
            variant="primary"
        >
            Open dropdown
        </Button>
    )}
    renderContent={() => <div>This is the dropdown content.</div>} />;

With More PaddingPermalink to this section

To apply more padding to the dropdown content, use the provided <DropdownContentWrapper> convenience wrapper. A paddingSize of "medium" is suitable for relatively larger dropdowns (default is "small").

const WithMorePadding = () => <Dropdown
    onClose={fn()}
    onToggle={fn()}
    renderContent={() => (
        <DropdownContentWrapper paddingSize="medium">
            { /* eslint-disable react/no-unescaped-entities */ }
            Content wrapped with <code>paddingSize="medium"</code>.
            { /* eslint-enable react/no-unescaped-entities */ }
        </DropdownContentWrapper>
    )} />;

With No PaddingPermalink to this section

The <DropdownContentWrapper> convenience wrapper can also be used to remove padding entirely, with a paddingSize of "none". This can also serve as a clean foundation to add arbitrary paddings, for example when child components already have padding on their own.

const WithNoPadding = () => <Dropdown
    onClose={fn()}
    onToggle={fn()}
    renderContent={() => (
        <DropdownContentWrapper paddingSize="none">
            { /* eslint-disable react/no-unescaped-entities */ }
            Content wrapped with <code>paddingSize="none"</code>.
            { /* eslint-enable react/no-unescaped-entities */ }
        </DropdownContentWrapper>
    )} />;

With Menu ItemsPermalink to this section

const WithMenuItems = () => <Dropdown
    onClose={fn()}
    onToggle={fn()}
    renderContent={() => (
        <>
            <MenuItem>Standalone Item</MenuItem>
            <MenuGroup label="Group 1">
                <MenuItem>Item 1</MenuItem>
                <MenuItem>Item 2</MenuItem>
            </MenuGroup>
            <MenuGroup label="Group 2">
                <MenuItem>Item 1</MenuItem>
                <MenuItem>Item 2</MenuItem>
            </MenuGroup>
        </>
    )} />;