Dropdown

Dropdown is a React component to render a button that opens a floating content modal when clicked.

This component takes care of updating the state of the dropdown menu (opened/closed), handles closing the menu when clicking outside and uses render props to render the button and the content.

Usage

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

const MyDropdown = () => (
    <Dropdown
        className="my-container-class-name"
        contentClassName="my-popover-content-classname"
        popoverProps={ { placement: 'bottom-start' } }
        renderToggle={ ( { isOpen, onToggle } ) => (
            <Button
                variant="primary"
                onClick={ onToggle }
                aria-expanded={ isOpen }
            >
                Toggle Popover!
            </Button>
        ) }
        renderContent={ () => <div>This is the content of the popover.</div> }
    />
);

Props

The component accepts the following props. Props not included in this set will be applied to the element wrapping Popover content.

className: string

className of the global container

• Required: No

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.

• Required: No

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.

• Required: No

expandOnMobile: boolean

Opt-in prop to show popovers fullscreen on mobile.

• Required: No
• Default: false

focusOnMount: ‘firstElement’ | boolean

By default, the first tabbable element in the popover will receive focus when it mounts. This is the same as setting this prop to "firstElement".

Specifying a true value will focus the container instead.

Specifying a false value disables the focus handling entirely (this should only be done when an appropriately accessible substitute behavior exists).

• Required: No
• Default: "firstElement"

headerTitle: string

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

• Required: No

onClose: () => void

A callback invoked when the popover should be closed.

• Required: No

open: boolean

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

• Required: No

onToggle: ( willOpen: boolean ) => void

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

• Required: No

popoverProps: WordPressComponentProps< Omit< PopoverProps, ‘children’ > ‘div’, false >

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.

• Required: No

renderContent: ( props: CallbackProps ) => ReactNode

A callback invoked to render the content of the dropdown menu.

• 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

• Required: Yes

renderToggle: ( props: CallbackProps ) => ReactNode

A callback invoked to render the Dropdown Toggle Button.

Its props are the same as the renderContent props.

• Required: Yes

style: React.CSSProperties

The style of the global container

• Required: No