www/docs/components/dropdowns.mdx
import DropdownBasic from '!!raw-loader!../examples/Dropdown/Basic'; import DropdownBasicButton from '!!raw-loader!../examples/Dropdown/BasicButton'; import DropdownButtonCustom from '!!raw-loader!../examples/Dropdown/ButtonCustom'; import DropdownButtonCustomMenu from '!!raw-loader!../examples/Dropdown/ButtonCustomMenu'; import DropdownButtonSizes from '!!raw-loader!../examples/Dropdown/ButtonSizes'; import DropDirections from '!!raw-loader!../examples/Dropdown/DropDirections'; import DropdownItemTags from '!!raw-loader!../examples/Dropdown/DropdownItemTags'; import MenuAlignEnd from '!!raw-loader!../examples/Dropdown/MenuAlignEnd'; import MenuAlignResponsive from '!!raw-loader!../examples/Dropdown/MenuAlignResponsive'; import MenuDividers from '!!raw-loader!../examples/Dropdown/MenuDividers'; import MenuHeaders from '!!raw-loader!../examples/Dropdown/MenuHeaders'; import SplitBasic from '!!raw-loader!../examples/Dropdown/SplitBasic'; import SplitVariants from '!!raw-loader!../examples/Dropdown/SplitVariants'; import DropdownVariants from '!!raw-loader!../examples/Dropdown/Variants'; import ButtonDark from '!!raw-loader!../examples/Dropdown/ButtonDark'; import NavbarDark from '!!raw-loader!../examples/Dropdown/NavbarDark'; import AutoClose from '!!raw-loader!../examples/Dropdown/AutoClose';
Dropdowns are toggleable, contextual overlays for displaying lists of links and more. Like overlays, Dropdowns are built using a third-party library <a href="https://popper.js.org/">Popper.js</a>, which provides dynamic positioning and viewport detection.
The <a href="https://www.w3.org/TR/wai-aria/"><abbr title="Web Accessibility Initiative">WAI</abbr> <AriaAbbr /></a> standard
defines a role="menu" widget, but it's very specific to a certain kind of menu. <AriaAbbr /> 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 <AriaAbbr /> authoring guidelines for menus.
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
<CodeBlock language="jsx" live> {DropdownVariants} </CodeBlock>Similarly, You create a split dropdown by combining the Dropdown components with another Button and a ButtonGroup.
<CodeBlock language="jsx" live> {SplitBasic} </CodeBlock>As with DropdownButton, SplitButton is provided as
convenience component.
Dropdowns work with buttons of all sizes.
<CodeBlock language="jsx" live> {DropdownButtonSizes} </CodeBlock>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.
:::caution Heads up!
Dark variants for components were deprecated in Bootstrap v5.3.0 with the introduction
of color modes. Instead of adding variant="dark", set data-bs-theme="dark" on the root
element, a parent wrapper, or the component itself.
:::
<CodeBlock language="jsx" live> {ButtonDark} </CodeBlock>Using menuVariant="dark" in a NavDropdown:
Trigger dropdown menus above, below, left, or to the right of their
toggle elements, with the drop prop.
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.
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>.
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.
:::danger Warning
Using responsive alignment will disable Popper usage so any dynamic positioning features such as <code>flip</code> will not work.
:::
<CodeBlock language="jsx" live> {MenuAlignResponsive} </CodeBlock>Add a header to label sections of actions.
<CodeBlock language="jsx" live previewClassName="static-dropdown-menu"> {MenuHeaders} </CodeBlock>Separate groups of related menu items with a divider.
<CodeBlock language="jsx" live previewClassName="static-dropdown-menu"> {MenuDividers} </CodeBlock>By default, the dropdown menu is closed when selecting a menu item or clicking outside of the
dropdown menu. This behaviour can be changed by using the autoClose property.
By default, autoClose is set to the default value true and behaves like expected. By choosing false, the dropdown
menu can only be toggled by clicking on the dropdown button. inside makes the dropdown disappear only
by choosing a menu item and outside closes the dropdown menu only by clicking outside.
Notice how the dropdown is toggled in each scenario by clicking on the button.
<CodeBlock language="jsx" live> {AutoClose} </CodeBlock>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
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.