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.
Dark dropdowns
Opt into darker dropdowns to match a dark navbar or custom style by adding
variant="dark"
onto an existing DropdownMenu
. Alternatively, use
menuVariant="dark"
when using the DropdownButton
component.
Using menuVariant="dark"
in a NavDropdown
:
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 align="end"
to a <Dropdown>
, <DropdownButton>
, or <SplitButton>
.
Responsive alignment
If you want to use responsive menu alignment, pass an object containing a breakpoint to the
align
prop on the <DropdownMenu>
, <DropdownButton>
, or <SplitButton>
.
You can specify start
or end
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 componentA 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
Name | Type | Default | Description |
---|---|---|---|
align | "start"|"end"|{ sm: "start"|"end" }|{ md: "start"|"end" }|{ lg: "start"|"end" }|{ xl: "start"|"end"}|{ xxl: "start"|"end"} | Aligns the dropdown menu. see DropdownMenu for more details | |
disabled | boolean | Disables both Buttons | |
href | string | An | |
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 | |
menuVariant | 'dark' | Menu color variant. Omitting this will use the default light color. | |
onClick | function | An | |
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 componentA 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
Name | Type | Default | Description |
---|---|---|---|
align | "start"|"end"|{ sm: "start"|"end" }|{ md: "start"|"end" }|{ lg: "start"|"end" }|{ xl: "start"|"end"}|{ xxl: "start"|"end"} | Aligns the dropdown menu. see DropdownMenu for more details | |
disabled | boolean | Disables both Buttons | |
href | string | An | |
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 | |
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 | |
title required | node | The content of the non-toggle Button. | |
toggleLabel | string | 'Toggle dropdown' | Accessible label for the toggle; the value of |
type | string | 'button' | A |
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 componentName | Type | Default | Description |
---|---|---|---|
align | "start"|"end"|{ sm: "start"|"end" }|{ md: "start"|"end" }|{ lg: "start"|"end" }|{ xl: "start"|"end"}|{ xxl: "start"|"end"} | 'start' | Aligns the dropdown menu to the specified side of the Dropdown toggle. You can
also align the menu responsively for breakpoints starting at Note: Using responsive alignment will disable Popper usage for positioning. |
as | elementType | You can use a custom element type for this component. | |
drop | 'up' | 'start' | 'end' | '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
The Default behavior is | |
navbar | boolean | false | |
onSelect | function | A callback fired when a menu item is selected.
| |
onToggle | function | controls show A callback fired when the Dropdown wishes to change visibility. Called with the requested
| |
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 componentName | Type | Default | Description |
---|---|---|---|
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 | |
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 componentName | Type | Default | Description |
---|---|---|---|
align | "start"|"end"|{ sm: "start"|"end" }|{ md: "start"|"end" }|{ lg: "start"|"end" }|{ xl: "start"|"end"}|{ xxl: "start"|"end"} | Aligns the dropdown menu to the specified side of the container. You can also align
the menu responsively for breakpoints starting at Note: Using responsive alignment will disable Popper usage for positioning. | |
as | elementType | <div> | Control the rendering of the DropdownMenu. All non-menu props
(listed here) are passed through to the If providing a custom, non DOM, component. the |
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
| |
show | boolean | Controls the visibility of the Dropdown menu | |
variant | string | Menu color variant. Omitting this will use the default light color. | |
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 componentName | 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 | string | number | Value passed to the | |
href | string | HTML | |
onClick | function | Callback fired when the menu item is clicked. | |
onSelect | function | Callback fired when the menu item is selected.
| |
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 componentName | 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. |
Dropdown.Dividerview source file
import Dropdown from 'react-bootstrap/Dropdown'
Copy import code for the Dropdown componentName | Type | Default | Description |
---|---|---|---|
as | elementType | <hr> | 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. |