Dropdowns

Toggle contextual overlays for displaying lists of links and more with the Bootstrap dropdown plugin

Overview

Dropdowns are toggleable, contextual overlays for displaying lists of links and more. Like overlays, Dropdowns are built using a third-party library Popper.js, which provides dynamic positioning and viewport detection.

Accessibility

The WAI ARIA standard defines a role="menu" widget, but it's very specific to a certain kind a menu. ARIA menus, must only contain role="menuitem", role="menuitemcheckbox", or role="menuitemradio".

On the other hand, Bootstrap's dropdowns are designed to more generic and application in a variety of situations. For this reason we don't automatically add the menu roles to the markup. We do implement some basic keyboard navigation, and if you do provide the "menu" role, react-bootstrap will do it's best to ensure the focus management is compliant with the ARIA authoring guidelines for menus.

Examples

Single button dropdowns

The basic Dropdown is composed of a wrapping Dropdown and inner <DropdownMenu>, and <DropdownToggle>. By default the <DropdownToggle> will render a Button component and accepts all the same props.

<Dropdown>
  <Dropdown.Toggle variant="success" id="dropdown-basic">
    Dropdown Button
  </Dropdown.Toggle>

  <Dropdown.Menu>
    <Dropdown.Item href="#/action-1">Action</Dropdown.Item>
    <Dropdown.Item href="#/action-2">Another action</Dropdown.Item>
    <Dropdown.Item href="#/action-3">Something else</Dropdown.Item>
  </Dropdown.Menu>
</Dropdown>;

Press esc to disable tab trapping

Since the above is such a common configuration react-bootstrap provide the <DropdownButton> component to help reduce typing. Provide a title prop and some <DropdownItem>s and you're ready to go.

<DropdownButton id="dropdown-basic-button" title="Dropdown button">
  <Dropdown.Item href="#/action-1">Action</Dropdown.Item>
  <Dropdown.Item href="#/action-2">Another action</Dropdown.Item>
  <Dropdown.Item href="#/action-3">Something else</Dropdown.Item>
</DropdownButton>;

Press esc to disable tab trapping

DropdownButton will forward Button props to the underlying Toggle component

<ButtonToolbar>
  {['Primary', 'Secondary', 'Success', 'Info', 'Warning', 'Danger'].map(
    variant => (
      <DropdownButton
        title={variant}
        variant={variant.toLowerCase()}
        id={`dropdown-variants-${variant}`}
        key={variant}
      >
        <Dropdown.Item eventKey="1">Action</Dropdown.Item>
        <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
        <Dropdown.Item eventKey="3" active>
          Active Item
        </Dropdown.Item>
        <Dropdown.Divider />
        <Dropdown.Item eventKey="4">Separated link</Dropdown.Item>
      </DropdownButton>
    ),
  )}
</ButtonToolbar>;

Press esc to disable tab trapping

Split button dropdowns

Similarly, You create a split dropdown by combining the Dropdown components with another Button and a ButtonGroup.

<Dropdown as={ButtonGroup}>
  <Button variant="success">Split Button</Button>

  <Dropdown.Toggle split variant="success" id="dropdown-split-basic" />

  <Dropdown.Menu>
    <Dropdown.Item hred="#/action-1">Action</Dropdown.Item>
    <Dropdown.Item hred="#/action-2">Another action</Dropdown.Item>
    <Dropdown.Item hred="#/action-3">Something else</Dropdown.Item>
  </Dropdown.Menu>
</Dropdown>;

Press esc to disable tab trapping

As with DropdownButton, SplitButton is provided as convenience component.

<ButtonToolbar>
  {['Primary', 'Secondary', 'Success', 'Info', 'Warning', 'Danger'].map(
    variant => (
      <SplitButton
        title={variant}
        variant={variant.toLowerCase()}
        id={`dropdown-split-variants-${variant}`}
        key={variant}
      >
        <Dropdown.Item eventKey="1">Action</Dropdown.Item>
        <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
        <Dropdown.Item eventKey="3" active>
          Active Item
        </Dropdown.Item>
        <Dropdown.Divider />
        <Dropdown.Item eventKey="4">Separated link</Dropdown.Item>
      </SplitButton>
    ),
  )}
</ButtonToolbar>;

Press esc to disable tab trapping

Sizing

Dropdowns work with buttons of all sizes.

<>
  <ButtonToolbar>
    {[DropdownButton, SplitButton].map((DropdownType, idx) => (
      <DropdownType
        size="lg"
        title="Drop small"
        id={`dropdown-button-drop-${idx}`}
        key={idx}
      >
        <Dropdown.Item eventKey="1">Action</Dropdown.Item>
        <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
        <Dropdown.Item eventKey="3">Something else here</Dropdown.Item>
        <Dropdown.Divider />
        <Dropdown.Item eventKey="4">Separated link</Dropdown.Item>
      </DropdownType>
    ))}
  </ButtonToolbar>
  <ButtonToolbar>
    {[DropdownButton, SplitButton].map((DropdownType, idx) => (
      <DropdownType
        size="sm"
        variant="secondary"
        title="Drop small"
        id={`dropdown-button-drop-${idx}`}
        key={idx}
      >
        <Dropdown.Item eventKey="1">Action</Dropdown.Item>
        <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
        <Dropdown.Item eventKey="3">Something else here</Dropdown.Item>
        <Dropdown.Divider />
        <Dropdown.Item eventKey="4">Separated link</Dropdown.Item>
      </DropdownType>
    ))}
  </ButtonToolbar>
</>;

Press esc to disable tab trapping

Drop directions

Trigger dropdown menus above, below, left, or to the right of their toggle elements, with the drop prop.

<>
  <ButtonToolbar>
    {['up', 'down', 'left', 'right'].map(direction => (
      <DropdownButton
        drop={direction}
        variant="secondary"
        title={` Drop ${direction} `}
        id={`dropdown-button-drop-${direction}`}
        key={direction}
      >
        <Dropdown.Item eventKey="1">Action</Dropdown.Item>
        <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
        <Dropdown.Item eventKey="3">Something else here</Dropdown.Item>
        <Dropdown.Divider />
        <Dropdown.Item eventKey="4">Separated link</Dropdown.Item>
      </DropdownButton>
    ))}
  </ButtonToolbar>

  <ButtonToolbar>
    {['up', 'down', 'left', 'right'].map(direction => (
      <SplitButton
        drop={direction}
        variant="secondary"
        title={`Drop ${direction}`}
        id={`dropdown-button-drop-${direction}`}
        key={direction}
      >
        <Dropdown.Item eventKey="1">Action</Dropdown.Item>
        <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
        <Dropdown.Item eventKey="3">Something else here</Dropdown.Item>
        <Dropdown.Divider />
        <Dropdown.Item eventKey="4">Separated link</Dropdown.Item>
      </SplitButton>
    ))}
  </ButtonToolbar>
</>;

Press esc to disable tab trapping

Historically dropdown menu contents had to be links, but that’s no longer the case with v4. Now you can optionally use <button> elements in your dropdowns instead of just <a>s.

<DropdownButton id="dropdown-item-button" title="Dropdown button">
  <Dropdown.Item as="button">Action</Dropdown.Item>
  <Dropdown.Item as="button">Another action</Dropdown.Item>
  <Dropdown.Item as="button">Something else</Dropdown.Item>
</DropdownButton>;

Press esc to disable tab trapping

By default, a dropdown menu is aligned to the left, but you can switch it by passing the alignRight prop.

<DropdownButton
  alignRight
  title="Dropdown right"
  id="dropdown-menu-align-right"
>
  <Dropdown.Item eventKey="1">Action</Dropdown.Item>
  <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
  <Dropdown.Item eventKey="3">Something else here</Dropdown.Item>
  <Dropdown.Divider />
  <Dropdown.Item eventKey="4">Separated link</Dropdown.Item>
</DropdownButton>;

Press esc to disable tab trapping

Add a header to label sections of actions.

<Dropdown.Menu show>
  <Dropdown.Header>Dropdown header</Dropdown.Header>
  <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
  <Dropdown.Item eventKey="3">Something else here</Dropdown.Item>
</Dropdown.Menu>;

Press esc to disable tab trapping

Separate groups of related menu items with a divider.

<Dropdown.Menu show>
  <Dropdown.Item eventKey="1">Action</Dropdown.Item>
  <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
  <Dropdown.Item eventKey="3">Something else here</Dropdown.Item>
  <Dropdown.Divider />
  <Dropdown.Item eventKey="4">Separated link</Dropdown.Item>
</Dropdown.Menu>;

Press esc to disable tab trapping

Customization

If the default handling of the dropdown menu and toggle components aren't to your liking, you can customize them, by using the more basic <Dropdown> Component to explicitly specify the Toggle and Menu components

<ButtonToolbar>
  <Dropdown>
    <Dropdown.Toggle id="dropdown-custom-1">Pow! Zoom!</Dropdown.Toggle>
    <Dropdown.Menu className="super-colors">
      <Dropdown.Item eventKey="1">Action</Dropdown.Item>
      <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
      <Dropdown.Item eventKey="3" active>
        Active Item
      </Dropdown.Item>
      <Dropdown.Divider />
      <Dropdown.Item eventKey="4">Separated link</Dropdown.Item>
    </Dropdown.Menu>
  </Dropdown>

  <Dropdown as={ButtonGroup}>
    <Button variant="info">mix it up style-wise</Button>
    <Dropdown.Toggle split variant="success" id="dropdown-custom-2" />
    <Dropdown.Menu className="super-colors">
      <Dropdown.Item eventKey="1">Action</Dropdown.Item>
      <Dropdown.Item eventKey="2">Another action</Dropdown.Item>
      <Dropdown.Item eventKey="3" active>
        Active Item
      </Dropdown.Item>
      <Dropdown.Divider />
      <Dropdown.Item eventKey="4">Separated link</Dropdown.Item>
    </Dropdown.Menu>
  </Dropdown>
</ButtonToolbar>;

Press esc to disable tab trapping

For those that want to customize everything, you can forgo the included Toggle and Menu components, and create your own. By providing custom components to the as prop, you can control how each component behaves. Custom toggle and menu components must be able to accept refs.

class CustomToggle extends React.Component {
  constructor(props, context) {
    super(props, context);

    this.handleClick = this.handleClick.bind(this);
  }

  handleClick(e) {
    e.preventDefault();

    this.props.onClick(e);
  }

  render() {
    return (
      <a href="" onClick={this.handleClick}>
        {this.props.children}
      </a>
    );
  }
}

class CustomMenu extends React.Component {
  constructor(props, context) {
    super(props, context);

    this.handleChange = this.handleChange.bind(this);

    this.state = { value: '' };
  }

  handleChange(e) {
    this.setState({ value: e.target.value.toLowerCase().trim() });
  }

  render() {
    const {
      children,
      style,
      className,
      'aria-labelledby': labeledBy,
    } = this.props;

    const { value } = this.state;

    return (
      <div style={style} className={className} aria-labelledby={labeledBy}>
        <FormControl
          autoFocus
          className="mx-3 my-2 w-auto"
          placeholder="Type to filter..."
          onChange={this.handleChange}
          value={value}
        />
        <ul className="list-unstyled">
          {React.Children.toArray(children).filter(
            child =>
              !value || child.props.children.toLowerCase().startsWith(value),
          )}
        </ul>
      </div>
    );
  }
}

render(
  <Dropdown>
    <Dropdown.Toggle as={CustomToggle} id="dropdown-custom-components">
      Custom toggle
    </Dropdown.Toggle>

    <Dropdown.Menu as={CustomMenu}>
      <Dropdown.Item eventKey="1">Red</Dropdown.Item>
      <Dropdown.Item eventKey="2">Blue</Dropdown.Item>
      <Dropdown.Item eventKey="3" active>
        Orange
      </Dropdown.Item>
      <Dropdown.Item eventKey="1">Red-Orange</Dropdown.Item>
    </Dropdown.Menu>
  </Dropdown>,
);

Press esc to disable tab trapping

API

import DropdownButton from 'react-bootstrap/DropdownButton'

A convenience component for simple or general use dropdowns. Renders a Button toggle and all children are passed directly to the default Dropdown.Menu.

All unknown props are passed through to the Dropdown component. Only the Button variant, size and bsPrefix props are passed to the toggle, along with menu related props are passed to the Dropdown.Menu

Name	Type	Default	Description
disabled	boolean		Disables both Buttons
href	string		An `href` passed to the Toggle component
id required	string\|number		An html id attribute for the Toggle button, necessary for assistive technologies, such as screen readers.
menuRole	string		An ARIA accessible role applied to the Menu component. When set to 'menu', The dropdown
onClick	function		An `onClick` handler passed to the Toggle component
rootCloseEvent	string		Which event when fired outside the component will cause it to be closed. see DropdownMenu for more details
title required	node		The content of the non-toggle Button.

SplitButtonview source file

import SplitButton from 'react-bootstrap/SplitButton'

Name	Type	Default	Description
disabled	boolean		Disables both Buttons
href	string		An `href` passed to the non-toggle Button
id required	string\|number		An html id attribute for the Toggle button, necessary for assistive technologies, such as screen readers.
menuRole	string		An ARIA accessible role applied to the Menu component. When set to 'menu', The dropdown
onClick	function		An `onClick` handler passed to the non-toggle Button
rootCloseEvent	string		Which event when fired outside the component will cause it to be closed. see DropdownMenu for more details
target	string		An anchor `target` passed to the non-toggle Button
title required	node		The content of the non-toggle Button.
toggleLabel	string	`'Toggle dropdown'`	Accessible label for the toggle; the value of `title` if not specified.

import Dropdown from 'react-bootstrap/Dropdown'

Name	Type	Default	Description
alignRight	boolean		Align the menu to the right side of the Dropdown toggle
as	elementType	`<div>`	You can use a custom element type for this component.
drop	`'up'` \| `'left'` \| `'right'` \| `'down'`		Determines the direction and location of the Menu in relation to it's Toggle.
flip	boolean		Allow Dropdown to flip in case of an overlapping on the reference element. For more information refer to Popper.js's flip docs.
onSelect	function		A callback fired when a menu item is selected. `(eventKey: any, event: Object) => any`
onToggle	function		controls `show` A callback fired when the Dropdown wishes to change visibility. Called with the requested `show` value, the DOM event, and the source that fired it: `'click'`,`'keydown'`,`'rootClose'`, or `'select'`. `function( isOpen: boolean, event: SyntheticEvent, metadata: { source: 'select' \| 'click' \| 'rootClose' \| 'keydown' } ): void`
show	boolean		controlled by: `onToggle`, initial prop: `defaultShow` Whether or not the Dropdown is visible.
bsPrefix	string	`'dropdown'`	Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized bootstrap css.

import Dropdown from 'react-bootstrap/Dropdown'

Name	Type	Default	Description
as	elementType	`<Button>`	You can use a custom element type for this component.
id required	string\|number		An html id attribute, necessary for assistive technologies, such as screen readers.
split	boolean
bsPrefix	string	`'dropdown-toggle'`	Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized bootstrap css.

import Dropdown from 'react-bootstrap/Dropdown'

Name	Type	Default	Description
alignRight	boolean	`false`	Aligns the Dropdown menu to the right of it's container.
as	elementType	`<div>`	Control the rendering of the DropdownMenu. All non-menu props (listed here) are passed through to the `as` Component. If providing a custom, non DOM, component. the `show`, `close` and `alignRight` props are also injected and should be handled appropriately.
flip	boolean	`true`	Have the dropdown switch to it's opposite placement when necessary to stay on screen.
onSelect	function
popperConfig	object		A set of popper options and props passed directly to react-popper's Popper component.
rootCloseEvent	`'click'` \| `'mousedown'`		Which event when fired outside the component will cause it to be closed Note: For custom dropdown components, you will have to pass the `rootCloseEvent` to `<RootCloseWrapper>` in your custom dropdown menu component (similarly to how it is implemented in `<Dropdown.Menu>`).
show	boolean		Controls the visibility of the Dropdown menu
bsPrefix	string	`'dropdown-menu'`	Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized bootstrap css.

import Dropdown from 'react-bootstrap/Dropdown'

Name	Type	Default	Description
active	boolean		Highlight the menu item as active.
as	elementType	`<SafeAnchor>`	You can use a custom element type for this component.
disabled	boolean	`false`	Disable the menu item, making it unselectable.
eventKey	any		Value passed to the `onSelect` handler, useful for identifying the selected menu item.
href	string		HTML `href` attribute corresponding to `a.href`.
onClick	function		Callback fired when the menu item is clicked.
onSelect	function		Callback fired when the menu item is selected. `(eventKey: any, event: Object) => any`
bsPrefix required	string	`'dropdown'`	Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized bootstrap css.

import Dropdown from 'react-bootstrap/Dropdown'

Name	Type	Default	Description
as	elementType	`<div>`	You can use a custom element type for this component.
bsPrefix required	string	`'dropdown-header'`	Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized bootstrap css.

import Dropdown from 'react-bootstrap/Dropdown'

Name	Type	Default	Description
as	elementType	`<div>`	You can use a custom element type for this component.
bsPrefix required	string	`'dropdown-divider'`	Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized bootstrap css.