Dropdown

Basic dropdowns

Basic dropdowns present users with a menu of items upon clicking a dropdown toggle. The isOpen property is used to determine whether the menu is opened or not.

All of the items in a dropdown list are created as <DropdownItem> components. The following example shows a few different states of dropdown items. As shown in this example, dropdown items may:

• Use the tooltip property to enable tooltip support.
• Use the isDisabled property to disable an item.
• Use the isAriaDisabled property to style an item as disabled, while still allowing the item to receive keyboard focus and display a tooltip.

This example also uses a <DropdownSeparator>, which adds a horizontal line that splits the menu into 2 sections.

Autofocus on dropdown expansion

A <DropdownItem> may use the autoFocus property so that it automatically receives focus when the menu is expanded. autoFocus cannot be applied to disabled dropdown items.

With groups of items

Use the <DropdownGroup> component to group sets of related dropdown items together. Use the isGrouped property on the Dropdown component to indicate that a dropdown contains grouped items.

With item descriptions

A <DropdownItem> may use the description property to provide users with more context. This description will appear in the menu below the dropdown item it corresponds to.

With custom content

You may replace standard dropdown items with custom content. If so, you must style the menu contents and manage focus within your custom implementation.

With router link items

<DropdownItem> may use the component property to include router links.

Toggle styling

You can adjust the styling of a <DropdownToggle> using the toggleVariant property. toggleVariant may be set to 'primary', 'secondary', or 'default'.

Plain text toggle

A toggle may be styled as plain text using the isText and isPlainproperties. The following example applies these properties to a <Dropdown> component.

Disabled toggles

A <DropdownToggle> may use the isDisabled property to disable the expansion of the dropdown menu.

Icon toggle

<DropdownToggle> may use a recognizable icon instead of a text label if text would take up too much room. Set the toggleIndicator property to {null} to remove the default dropdown toggle caret.

Kebab toggle

Use <KebabToggle> to replace the default text label and caret with a kebab icon. A kebab toggle can be used to indicate that a dropdown connects to a menu.

Toggle with image

The icon property can be used to display an image in the DropdownToggle and can be used alongside a text label.

Toggle with badge

You may use a <BadgeToggle> to display the number of dropdown menu items.

Split button (checkbox)

To combine an action button or other control with a dropdown menu, use a split button. A <DropdownToggle> can be rendered as a split button by using the splitButtonItems property. Elements to be displayed before the toggle button must be included in splitButtonItems.

The following example shows a split button with a <DropdownToggleCheckbox>, which is primarily used for bulk select operations on large data sets.

Split button (checkbox with toggle text)

Text labels may optionally be used alongside actions within split buttons.

Split button (progress checkbox) Beta

The isInProgress property can be used to indicate a progress state by rendering a spinner in place of a checkbox.

Split button toggle variants

Use the toggleVariant and splitButtonVariant properties to adjust the styling of split button toggles.

The following example uses toggleVariant="primary" to apply primary visual styling and splitButtonVariant="action" to include an action.

Dropdown alignment

The alignment of a dropdown menu may be changed to better fit the size of a user's browser window. A <Dropdown> may use the alignments property to indicate how the menu will align at different screen sizes.

Right-positioned menu

The following example demonstrates a <Dropdown> with a position equal to 'right'. By default, a dropdown menu is left-positioned, but a right-positioned menu may work better depending on where your dropdown is placed on a page.

Upwards directional menu

The following example demonstrates a <Dropdown> with a direction equal to 'up'. This will alter the default menu behavior so that the dropdown menu is displayed above the dropdown toggle.

Using document parent element

Avoid passing in document.body to a <Dropdown> menuAppendTo property. Doing so can cause accessibility issues, such as being unable to navigate <Dropdown> options using keyboards or screen readers.

Instead, append to ‘parent’ to avoid sacrificing accessibility.

The following example demonstrates both methods of appending. After making a selection, both dropdowns retain focus on their respective <Dropdown>, but the options for the document.body variant cannot be navigated via Voice Over.