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 of 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 its 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.

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

    DropdownButton will forward Button props to the underlying Toggle component

    Split button dropdowns

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

    As with DropdownButton, SplitButton is provided as convenience component.

    Sizing

    Dropdowns work with buttons of all sizes.

    Drop directions

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

    Dropdown items

    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.

    You can also create non-interactive dropdown items with <Dropdown.ItemText>. Feel free to style further with custom CSS or text utilities.

    Menu alignment

    By default, a dropdown menu is aligned to the left, but you can switch it by passing right to the align prop on a <DropdownMenu> or passing right to the menuAlign prop on the <DropdownButton> or <SplitButton> as seen below.

    Responsive alignment

    If you want to use responsive menu alignment, pass an object to the align prop on the <DropdownMenu> or the menuAlign prop on the <DropdownButton> and <SplitButton>. You can specify the directions left or right for the various breakpoints.

    Menu headers

    Add a header to label sections of actions.

    Menu dividers

    Separate groups of related menu items with a divider.

    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

    Custom Dropdown Components

    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.

    API

    DropdownButtonview source file

    import DropdownButton from 'react-bootstrap/DropdownButton'Copy import code for the DropdownButton component

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

    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

    NameTypeDefaultDescription
    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.

    menuAlign
    "left"|"right"|{ sm: "left"|"right" }|{ md: "left"|"right" }|{ lg: "left"|"right" }|{ xl: "left"|"right"}

    Aligns the dropdown menu responsively.

    see DropdownMenu for more details

    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

    renderMenuOnMount
    boolean

    Whether to render the dropdown menu in the DOM before the first time it is shown

    rootCloseEvent
    string

    Which event when fired outside the component will cause it to be closed.

    see DropdownMenu for more details

    size
    string

    Component size variations.

    title required
    node

    The content of the non-toggle Button.

    variant
    string

    Component visual or contextual style variants.

    bsPrefix
    string

    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.

    SplitButtonview source file

    import SplitButton from 'react-bootstrap/SplitButton'Copy import code for the SplitButton component

    A convenience component for simple or general use split button dropdowns. Renders a ButtonGroup containing a Button and a Button toggle for the Dropdown. All children are passed directly to the default Dropdown.Menu. This component accepts all of Dropdown's props.

    All unknown props are passed through to the Dropdown component. The Button variant, size and bsPrefix props are passed to the button and toggle, and menu-related props are passed to the Dropdown.Menu

    NameTypeDefaultDescription
    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.

    menuAlign
    "left"|"right"|{ sm: "left"|"right" }|{ md: "left"|"right" }|{ lg: "left"|"right" }|{ xl: "left"|"right"}

    Aligns the dropdown menu responsively.

    see DropdownMenu for more details

    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

    renderMenuOnMount
    boolean

    Whether to render the dropdown menu in the DOM before the first time it is shown

    rootCloseEvent
    string

    Which event when fired outside the component will cause it to be closed.

    see DropdownMenu for more details

    size
    string

    Component size variations.

    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.

    type
    string
    		'button'

    A type passed to the non-toggle Button

    variant
    string

    Component visual or contextual style variants.

    bsPrefix
    string

    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.

    Dropdownview source file

    import Dropdown from 'react-bootstrap/Dropdown'Copy import code for the Dropdown component
    NameTypeDefaultDescription
    alignRight
    boolean

    Align the menu to the right side of the Dropdown toggle

    as
    elementType

    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.

    focusFirstItemOnShow
    false | true | 'keyboard'

    Controls the focus behavior for when the Dropdown is opened. Set to true to always focus the first menu item, keyboard to focus only when navigating via the keyboard, or false to disable completely

    The Default behavior is false unless the Menu has a role="menu" where it will default to keyboard to match the recommended ARIA Authoring practices.

    navbar
    boolean
    		false
    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.

    Dropdown.Toggleview source file

    import Dropdown from 'react-bootstrap/Dropdown'Copy import code for the Dropdown component
    NameTypeDefaultDescription
    as
    elementType
    		<Button>

    You can use a custom element type for this component.

    childBsPrefix
    string

    to passthrough to the underlying button or whatever from DropdownButton

    eventKey
    any

    A unique identifier for the Component, the eventKey makes it distinguishable from others in a set. Similar to React's key prop, in that it only needs to be unique amongst the Components siblings, not globally.

    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.

    Dropdown.Menuview source file

    import Dropdown from 'react-bootstrap/Dropdown'Copy import code for the Dropdown component
    NameTypeDefaultDescription
    align
    "left"|"right"|{ sm: "left"|"right" }|{ md: "left"|"right" }|{ lg: "left"|"right" }|{ xl: "left"|"right"}
    		'left'

    Aligns the dropdown menu to the specified side of the container. You can also align the menu responsively for breakpoints starting at sm and up. The alignment direction will affect the specified breakpoint or larger.

    Note: Using responsive alignment will disable Popper usage for positioning.

    alignRight
    boolean
    		false
    Deprecated: Use align="right"

    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 Popper.

    renderOnMount
    boolean

    Whether to render the dropdown menu in the DOM before the first time it is shown

    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.

    Dropdown.Itemview source file

    import Dropdown from 'react-bootstrap/Dropdown'Copy import code for the Dropdown component
    NameTypeDefaultDescription
    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
    string
    		'dropdown-item'

    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.

    Dropdown.Headerview source file

    import Dropdown from 'react-bootstrap/Dropdown'Copy import code for the Dropdown component
    NameTypeDefaultDescription
    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.

    Dropdown.Dividerview source file

    import Dropdown from 'react-bootstrap/Dropdown'Copy import code for the Dropdown component
    NameTypeDefaultDescription
    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.