Dropdown – Automattic Design System

Import

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

Props

Name	Type	Required	Description
`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.
`expandOnMobile`	`boolean`		Opt-in prop to show popovers fullscreen on mobile. @default false
`focusOnMount`	`useFocusOnMount.Mode`		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. @default ‘firstElement’
`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< typeof Popover >, 'children' >`		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`	`( props: CallbackProps ) => ReactNode`	Yes	A callback invoked to render the content of the dropdown menu. Its first argument is the same as the renderToggle prop.
`renderToggle`	`( props: CallbackProps ) => ReactNode`	Yes	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.
`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.

Examples

Default

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 Padding

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 Padding

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 Items

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>
        </>
    )} />;