Dropdown

Overview

Toggle dropdown menus with buttons whenever possible. Here's an example using a Bootstrap button:

HTML

<div class="dropdown">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Toggle dropdown
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Dropdown item 1</a></li>
    <li><a class="dropdown-item" href="#">Dropdown item 2</a></li>
    <li><a class="dropdown-item" href="#">Dropdown item 3</a></li>
  </ul>
</div>

Dropdowns are toggleable, contextual overlays for displaying lists of links and more. They’re made interactive with the included Bootstrap dropdown JavaScript plugin. They’re toggled by clicking, not by hovering; this is an intentional design decision.

Dropdowns are built on a third party library, Floating UI, which provides dynamic positioning and viewport detection. Be sure to include floating-ui.dom.umd.min.js before Bootstrap's JavaScript or use bootstrap.bundle.min.js / bootstrap.bundle.js which contains Floating UI. Popper isn't used to position dropdowns in navbars though as dynamic positioning isn't required.

Examples

Wrap the dropdown’s toggle (your button or link) and the dropdown menu within .dropdown, or another element that declares position: relative;. Ideally, you should use a <button> element as the dropdown trigger, but the plugin will work with <a> elements as well. The examples shown here use semantic <ul> elements where appropriate, but custom markup is supported.

Single button

While <button> is the recommended control for a dropdown toggle, there might be situations where you have to use an <a> element. If you do, we recommend adding a role="button" attribute to appropriately convey control’s purpose to assistive technologies such as screen readers.

HTML

<div class="dropdown">
  <a class="btn btn-solid theme-secondary" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">
    Toggle dropdown
  </a>

  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Dropdown item 1</a></li>
    <li><a class="dropdown-item" href="#">Dropdown item 2</a></li>
    <li><a class="dropdown-item" href="#">Dropdown item 3</a></li>
  </ul>
</div>

Split button

Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of .dropdown-toggle-split for proper spacing around the dropdown caret.

We use this extra class to reduce the horizontal padding on either side of the caret by 25% and remove the margin-left that’s added for regular button dropdowns. Those extra changes keep the caret centered in the split button and provide a more appropriately sized hit area next to the main button.

HTML

<!-- Example split danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger">Danger</button>
  <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
    <li><a class="dropdown-item" href="#">Something else here</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Separated link</a></li>
  </ul>
</div>

Dark dropdowns

Opt into darker dropdowns to match a dark navbar or custom style by adding data-bs-theme="dark" onto an existing .dropdown-menu. No changes are required to the dropdown items.

HTML

<div class="dropdown" data-bs-theme="dark">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown button
  </button>
  <ul class="dropdown-menu dropdown-menu-dark">
    <li><a class="dropdown-item active" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
    <li><a class="dropdown-item" href="#">Something else here</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Separated link</a></li>
  </ul>
</div>

And putting it to use in a navbar:

HTML

<nav class="navbar navbar-expand-lg navbar-dark bg-dark">
  <div class="container-fluid">
    <a class="navbar-brand" href="#">Navbar</a>
    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNavDarkDropdown" aria-controls="navbarNavDarkDropdown" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>
    <div class="collapse navbar-collapse" id="navbarNavDarkDropdown">
      <ul class="navbar-nav">
        <li class="nav-item dropdown" data-bs-theme="dark">
          <button class="btn btn-dark dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
            Dropdown
          </button>
          <ul class="dropdown-menu dropdown-menu-dark">
            <li><a class="dropdown-item" href="#">Action</a></li>
            <li><a class="dropdown-item" href="#">Another action</a></li>
            <li><a class="dropdown-item" href="#">Something else here</a></li>
          </ul>
        </li>
      </ul>
    </div>
  </div>
</nav>

Placement

Use data-bs-placement on the toggle element to control where the dropdown menu appears.

Physical placements: top, bottom, left, right — fixed directions regardless of text direction.

Logical placements: start, end — automatically flip based on RTL. In LTR mode, start becomes left and end becomes right. In RTL mode, they swap.

All placements support -start and -end alignment modifiers (e.g., bottom-start, end-end).

Placement type

Physical Logical

Placement

HTML

<div class="dropdown">
  <button class="btn btn-solid theme-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-placement="bottom-start" aria-expanded="false">
    Toggle dropdown
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
    <li><a class="dropdown-item" href="#">Something else here</a></li>
  </ul>
</div>

Responsive

Change placement at different breakpoints using responsive prefixes. The syntax is breakpoint:placement, where breakpoint is one of sm, md, lg, xl, or 2xl. Multiple breakpoints can be combined in a single attribute, space-separated.

For example, data-bs-placement="bottom-start md:bottom-end lg:end-start" will:

Show the menu at bottom-start on small screens (default)
Switch to bottom-end at the md breakpoint
Switch to right-start at the lg breakpoint

HTML

<div class="dropdown">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" data-bs-placement="bottom-start md:bottom-end" aria-expanded="false">
    Bottom start → md:bottom-end
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
  </ul>
</div>
<div class="dropdown">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" data-bs-placement="bottom lg:right" aria-expanded="false">
    Bottom → lg:right
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
  </ul>
</div>
<div class="dropdown">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" data-bs-placement="top-end md:right-start xl:bottom-start" aria-expanded="false">
    Multi-breakpoint
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
  </ul>
</div>

Resize your browser window to see the placement change at different breakpoints.

You can use <a> or <button> elements as dropdown items.

We use utility classes to display dropdown menus in our docs examples, but they're not required for your own use.

HTML

<ul class="dropdown-menu show position-static">
  <li><button class="dropdown-item" type="button">Action</button></li>
  <li><button class="dropdown-item" type="button">Another action</button></li>
  <li><button class="dropdown-item" type="button">Something else here</button></li>
</ul>

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

HTML

<ul class="dropdown-menu show position-static">
  <li><span class="dropdown-item-text">Dropdown item text</span></li>
  <li><a class="dropdown-item" href="#">Action</a></li>
  <li><a class="dropdown-item" href="#">Another action</a></li>
  <li><a class="dropdown-item" href="#">Something else here</a></li>
</ul>

Active

Add .active to items in the dropdown to style them as the active selection. To convey the active state to assistive technologies, use the aria-current attribute — using the page value for the current page, or true for the current item in a set.

HTML

<ul class="dropdown-menu show position-static">
  <li><a class="dropdown-item" href="#">Regular link</a></li>
  <li><a class="dropdown-item active" href="#" aria-current="true">Active link</a></li>
  <li><a class="dropdown-item" href="#">Another link</a></li>
</ul>

Disabled

Add .disabled to items in the dropdown to style them as disabled.

HTML

<ul class="dropdown-menu show position-static">
  <li><a class="dropdown-item" href="#">Regular link</a></li>
  <li><a class="dropdown-item disabled" aria-disabled="true">Disabled link</a></li>
  <li><a class="dropdown-item" href="#">Another link</a></li>
</ul>

Headers

Add a header to label sections of actions in any dropdown menu.

HTML

<ul class="dropdown-menu show position-static">
  <li><a class="dropdown-item" href="#">Action</a></li>
  <li><a class="dropdown-item" href="#">Action</a></li>
  <li><h6 class="dropdown-header">Dropdown header</h6></li>
  <li><a class="dropdown-item" href="#">Another action</a></li>
</ul>

Dividers

Separate groups of related menu items with a divider.

HTML

<ul class="dropdown-menu show position-static">
  <li><a class="dropdown-item" href="#">Action</a></li>
  <li><a class="dropdown-item" href="#">Another action</a></li>
  <li><a class="dropdown-item" href="#">Something else here</a></li>
  <li><hr class="dropdown-divider"></li>
  <li><a class="dropdown-item" href="#">Separated link</a></li>
</ul>

Text

Place any freeform text within a dropdown menu with text and use margin and padding utilities. Note that you’ll likely need additional sizing styles to constrain the menu width.

HTML

<div class="dropdown-menu show position-static p-3 text-body-secondary"
     style="--bs-dropdown-min-width: 240px;">
  <p>
    Some example text that’s free-flowing within the dropdown menu.
  </p>
  <p class="mb-0">
    And this is more example text.
  </p>
</div>

Forms

Put a form within a dropdown menu, or make it into a dropdown menu, and use margin and padding utilities to give it the negative space you require.

HTML

<div class="dropdown-menu show position-static"
     style="--bs-dropdown-min-width: 300px;">
  <form class="d-flex flex-column gap-3 p-3">
    <div>
      <label for="exampleDropdownFormEmail1" class="form-label">Email address</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="email@example.com">
    </div>
    <div>
      <label for="exampleDropdownFormPassword1" class="form-label">Password</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
    </div>
    <b-checkgroup>
      <div class="check">
        <input type="checkbox" id="checkLabel" />
        <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
          <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
          <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
        </svg>
      </div>
      <label for="checkLabel">Example new checkbox</label>
    </b-checkgroup>
    <div class="vstack gap-2">
      <button type="submit" class="btn-solid theme-primary">Sign in</button>
      <a class="btn-ghost theme-secondary" href="#">New around here? Sign up</a>
      <a class="btn-ghost theme-secondary" href="#">Forgot password?</a>
    </div>
  </form>
</div>

Submenus

Create nested dropdown menus with the .dropdown-submenu wrapper class. Submenus support hover and click activation, keyboard navigation, viewport-aware positioning, and mobile slide-over behavior.

Wrap a .dropdown-item trigger and a nested .dropdown-menu inside a .dropdown-submenu element.

HTML

<div class="dropdown">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown with submenu
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
    <li class="dropdown-divider"></li>
    <li class="dropdown-submenu">
      <button class="dropdown-item" type="button">More options</button>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">Sub-action 1</a></li>
        <li><a class="dropdown-item" href="#">Sub-action 2</a></li>
        <li><a class="dropdown-item" href="#">Sub-action 3</a></li>
      </ul>
    </li>
    <li><a class="dropdown-item" href="#">Something else</a></li>
  </ul>
</div>

Nested submenus

Submenus can be nested to multiple levels. Each level opens to the side and flips direction when there's not enough viewport space.

HTML

<div class="dropdown">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Multi-level menu
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Level 1 action</a></li>
    <li class="dropdown-submenu">
      <button class="dropdown-item" type="button">Level 1 submenu</button>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">Level 2 action</a></li>
        <li class="dropdown-submenu">
          <button class="dropdown-item" type="button">Level 2 submenu</button>
          <ul class="dropdown-menu">
            <li><a class="dropdown-item" href="#">Level 3 action A</a></li>
            <li><a class="dropdown-item" href="#">Level 3 action B</a></li>
          </ul>
        </li>
        <li><a class="dropdown-item" href="#">Another level 2</a></li>
      </ul>
    </li>
    <li><a class="dropdown-item" href="#">Another level 1</a></li>
  </ul>
</div>

Multiple submenus

When multiple submenu triggers exist at the same level, opening one automatically closes the others.

HTML

<div class="dropdown">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Multiple submenus
  </button>
  <ul class="dropdown-menu">
    <li class="dropdown-submenu">
      <button class="dropdown-item" type="button">File</button>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">New</a></li>
        <li><a class="dropdown-item" href="#">Open</a></li>
        <li><a class="dropdown-item" href="#">Save</a></li>
      </ul>
    </li>
    <li class="dropdown-submenu">
      <button class="dropdown-item" type="button">Edit</button>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">Cut</a></li>
        <li><a class="dropdown-item" href="#">Copy</a></li>
        <li><a class="dropdown-item" href="#">Paste</a></li>
      </ul>
    </li>
    <li class="dropdown-submenu">
      <button class="dropdown-item" type="button">View</button>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">Zoom In</a></li>
        <li><a class="dropdown-item" href="#">Zoom Out</a></li>
      </ul>
    </li>
    <li class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Preferences</a></li>
  </ul>
</div>

Use data-bs-offset or data-bs-reference to change the location of the dropdown.

HTML

<div class="d-flex">
  <div class="dropdown me-1">
    <button type="button" class="btn btn-solid theme-secondary" data-bs-toggle="dropdown" aria-expanded="false" data-bs-offset="10,20">
      Offset
    </button>
    <ul class="dropdown-menu">
      <li><a class="dropdown-item" href="#">Action</a></li>
      <li><a class="dropdown-item" href="#">Another action</a></li>
      <li><a class="dropdown-item" href="#">Something else here</a></li>
    </ul>
  </div>
  <div class="btn-group">
    <button type="button" class="btn btn-solid theme-secondary">Reference</button>
    <button type="button" class="btn btn-solid theme-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false" data-bs-reference="parent">
      <span class="visually-hidden">Toggle Dropdown</span>
    </button>
    <ul class="dropdown-menu">
      <li><a class="dropdown-item" href="#">Action</a></li>
      <li><a class="dropdown-item" href="#">Another action</a></li>
      <li><a class="dropdown-item" href="#">Something else here</a></li>
      <li><hr class="dropdown-divider"></li>
      <li><a class="dropdown-item" href="#">Separated link</a></li>
    </ul>
  </div>
</div>

Auto close behavior

By default, the dropdown menu is closed when clicking inside or outside the dropdown menu. You can use the autoClose option to change this behavior of the dropdown.

HTML

<div class="btn-group">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" data-bs-auto-close="true" aria-expanded="false">
    Default dropdown
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" data-bs-auto-close="inside" aria-expanded="false">
    Clickable inside
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" data-bs-auto-close="outside" aria-expanded="false">
    Clickable outside
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-solid theme-secondary" type="button" data-bs-toggle="dropdown" data-bs-auto-close="false" aria-expanded="false">
    Manual close
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

Accessibility

The WAI ARIA standard defines an actual role="menu" widget, but this is specific to application-like menus which trigger actions or functions. ARIA menus can only contain menu items, checkbox menu items, radio button menu items, radio button groups, and sub-menus.

Bootstrap's dropdowns, on the other hand, are designed to be generic and applicable to a variety of situations and markup structures. For instance, it is possible to create dropdowns that contain additional inputs and form controls, such as search fields or login forms. For this reason, Bootstrap does not expect (nor automatically add) any of the role and aria- attributes required for true ARIA menus. Authors will have to include these more specific attributes themselves.

Dropdowns include built-in keyboard support for navigating menu items.

Key	Action
`↓` / `↑`	Navigate to next/previous menu item
`→`	Enter submenu (or `←` in RTL)
`←`	Exit submenu and return to parent (or `→` in RTL)
`Enter` / `Space`	Activate focused item or open submenu
`Esc`	Close the dropdown menu
`Home` / `End`	Jump to first/last menu item
`Tab`	Move focus and close the dropdown

CSS

Variables

Dropdowns use local CSS variables on .dropdown-menu for real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

SCSS

--dropdown-zindex: #{$zindex-dropdown};
--dropdown-gap: #{$dropdown-gap};
--dropdown-min-width: #{$dropdown-min-width};
--dropdown-padding-x: #{$dropdown-padding-x};
--dropdown-padding-y: #{$dropdown-padding-y};
--dropdown-spacer: #{$dropdown-spacer};
--dropdown-font-size: #{$dropdown-font-size};
--dropdown-color: #{$dropdown-color};
--dropdown-bg: #{$dropdown-bg};
--dropdown-border-color: #{$dropdown-border-color};
--dropdown-border-radius: #{$dropdown-border-radius};
--dropdown-border-width: #{$dropdown-border-width};
--dropdown-inner-border-radius: #{$dropdown-inner-border-radius};
--dropdown-divider-bg: #{$dropdown-divider-bg};
--dropdown-divider-margin-y: #{$dropdown-divider-margin-y};
--dropdown-divider-margin-x: #{$dropdown-divider-margin-x};
--dropdown-box-shadow: #{$dropdown-box-shadow};
--dropdown-link-color: #{$dropdown-link-color};
--dropdown-link-hover-color: #{$dropdown-link-hover-color};
--dropdown-link-hover-bg: #{$dropdown-link-hover-bg};
--dropdown-link-active-color: #{$dropdown-link-active-color};
--dropdown-link-active-bg: #{$dropdown-link-active-bg};
--dropdown-link-disabled-color: #{$dropdown-link-disabled-color};
--dropdown-item-gap: #{$dropdown-item-gap};
--dropdown-item-padding-x: #{$dropdown-item-padding-x};
--dropdown-item-padding-y: #{$dropdown-item-padding-y};
--dropdown-item-border-radius: #{$dropdown-item-border-radius};
--dropdown-header-color: #{$dropdown-header-color};
--dropdown-header-padding-x: #{$dropdown-header-padding-x};
--dropdown-header-padding-y: #{$dropdown-header-padding-y};

Dropdown items include at least one variable that is not set on .dropdown. This allows you to provide a new value while Bootstrap defaults to a fallback value.

--bs-dropdown-item-border-radius

Customization through CSS variables can be seen on the .dropdown-menu-dark class where we override specific values without adding duplicate CSS selectors.

SCSS

--dropdown-color: #{$dropdown-dark-color};
--dropdown-bg: #{$dropdown-dark-bg};
--dropdown-border-color: #{$dropdown-dark-border-color};
--dropdown-box-shadow: #{$dropdown-dark-box-shadow};
--dropdown-link-color: #{$dropdown-dark-link-color};
--dropdown-link-hover-color: #{$dropdown-dark-link-hover-color};
--dropdown-divider-bg: #{$dropdown-dark-divider-bg};
--dropdown-link-hover-bg: #{$dropdown-dark-link-hover-bg};
--dropdown-link-active-color: #{$dropdown-dark-link-active-color};
--dropdown-link-active-bg: #{$dropdown-dark-link-active-bg};
--dropdown-link-disabled-color: #{$dropdown-dark-link-disabled-color};
--dropdown-header-color: #{$dropdown-dark-header-color};

Sass variables

Variables for all dropdowns:

SCSS

$dropdown-gap:                      $spacer * .125;
$dropdown-min-width:                10rem;
$dropdown-padding-x:                .25rem;
$dropdown-padding-y:                .25rem;
$dropdown-spacer:                   .125rem;
$dropdown-font-size:                $font-size-base;
$dropdown-color:                    var(--fg-body);
$dropdown-bg:                       var(--bg-body);
$dropdown-border-color:             var(--border-color-translucent);
$dropdown-border-radius:            var(--border-radius-lg);
$dropdown-border-width:             var(--border-width);
$dropdown-inner-border-radius:      calc(#{$dropdown-border-radius} - #{$dropdown-border-width});
$dropdown-box-shadow:               var(--box-shadow);

$dropdown-divider-bg:               $dropdown-border-color;
$dropdown-divider-margin-y:         $spacer * .125;
$dropdown-divider-margin-x:         $spacer * .25;

$dropdown-link-color:               var(--fg-body);
$dropdown-link-hover-color:         $dropdown-link-color;
$dropdown-link-hover-bg:            var(--bg-1);

$dropdown-link-active-color:        $component-active-color;
$dropdown-link-active-bg:           $component-active-bg;

$dropdown-link-disabled-color:      var(--fg-3);

$dropdown-item-padding-y:           $spacer * .25;
$dropdown-item-padding-x:           $spacer * .75;
$dropdown-item-border-radius:       var(--border-radius);
$dropdown-item-gap:                 $spacer * .5;

$dropdown-header-color:             var(--gray-600);
$dropdown-header-padding-x:         $dropdown-item-padding-x;
$dropdown-header-padding-y:         $dropdown-padding-y;

Variables for the dark dropdown:

SCSS

$dropdown-dark-color:               var(--gray-300);
$dropdown-dark-bg:                  var(--gray-900);
$dropdown-dark-border-color:        $dropdown-border-color;
$dropdown-dark-divider-bg:          $dropdown-divider-bg;
$dropdown-dark-box-shadow:          null;
$dropdown-dark-link-color:          $dropdown-dark-color;
$dropdown-dark-link-hover-color:    $white;
$dropdown-dark-link-hover-bg:       rgba($white, .15);
$dropdown-dark-link-active-color:   $dropdown-link-active-color;
$dropdown-dark-link-active-bg:      $dropdown-link-active-bg;
$dropdown-dark-link-disabled-color: var(--gray-500);
$dropdown-dark-header-color:        var(--gray-500);

Variables for the CSS-based carets that indicate a dropdown’s interactivity:

SCSS

$caret-width:                 .3em;
$caret-vertical-align:        $caret-width * .85;
$caret-spacing:               $caret-width * .85;

Sass mixins

Mixins are used to generate the CSS-based carets and can be found in scss/mixins/_caret.scss.

SCSS

@mixin caret-down($width: $caret-width) {
  border-block-start: $width solid;
  border-block-end: 0;
  border-inline-start: $width solid transparent;
  border-inline-end: $width solid transparent;
}

@mixin caret-up($width: $caret-width) {
  border-block-start: 0;
  border-block-end: $width solid;
  border-inline-start: $width solid transparent;
  border-inline-end: $width solid transparent;
}

@mixin caret-end($width: $caret-width) {
  border-block-start: $width solid transparent;
  border-block-end: $width solid transparent;
  border-inline-start: $width solid;
  border-inline-end: 0;
}

@mixin caret-start($width: $caret-width) {
  border-block-start: $width solid transparent;
  border-block-end: $width solid transparent;
  border-inline-end: $width solid;
}

@mixin caret(
  $direction: down,
  $width: $caret-width,
  $spacing: $caret-spacing,
  $vertical-align: $caret-vertical-align
) {
  @if $enable-caret {
    &::after {
      display: inline-block;
      margin-inline-start: $spacing;
      vertical-align: $vertical-align;
      content: "";
      @if $direction == down {
        @include caret-down($width);
      } @else if $direction == up {
        @include caret-up($width);
      } @else if $direction == end {
        @include caret-end($width);
      }
    }

    @if $direction == start {
      &::after {
        display: none;
      }

      &::before {
        display: inline-block;
        margin-inline-end: $spacing;
        vertical-align: $vertical-align;
        content: "";
        @include caret-start($width);
      }
    }

    &:empty::after {
      margin-inline-start: 0;
    }
  }
}

Usage

Via data attributes or JavaScript, the dropdown plugin toggles hidden content (dropdown menus) by toggling the .show class on the parent .dropdown-menu. The data-bs-toggle="dropdown" attribute is relied on for closing dropdown menus at an application level, so it’s a good idea to always use it.

On touch-enabled devices, opening a dropdown adds empty mouseover handlers to the immediate children of the <body> element. This admittedly ugly hack is necessary to work around a quirk in iOs’ event delegation, which would otherwise prevent a tap anywhere outside of the dropdown from triggering the code that closes the dropdown. Once the dropdown is closed, these additional empty mouseover handlers are removed.

Via data attributes

Add data-bs-toggle="dropdown" to a link or button to toggle a dropdown.

HTML

<div class="dropdown">
  <button type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown trigger
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</div>

Via JavaScript

Dropdowns must have data-bs-toggle="dropdown" on their trigger element, regardless of whether you call your dropdown via JavaScript or use the data-api.

Call the dropdowns via JavaScript:

JavaScript

const dropdownElementList = document.querySelectorAll('[data-bs-toggle="dropdown"]')
const dropdownList = [...dropdownElementList].map(dropdownToggleEl => new bootstrap.Dropdown(dropdownToggleEl))

Dependencies

The dropdown plugin requires the following JavaScript files if you're building Bootstrap's JS from source:

File	Description
`js/src/dropdown.js`	Main dropdown component
`js/src/base-component.js`	Base component class
`js/src/dom/event-handler.js`	Event handling utilities
`js/src/dom/manipulator.js`	Data attribute manipulation
`js/src/dom/selector-engine.js`	DOM selector utilities
`js/src/util/index.js`	Core utility functions
`js/src/util/floating-ui.js`	Responsive placement utilities
`@floating-ui/dom`	Third-party positioning library

Options

As options can be passed via data attributes or JavaScript, you can append an option name to data-bs-, as in data-bs-animation="{value}". Make sure to change the case type of the option name from “camelCase” to “kebab-case” when passing the options via data attributes. For example, use data-bs-custom-class="beautifier" instead of data-bs-customClass="beautifier".

As of Bootstrap 5.2.0, all components support an experimental reserved data attribute data-bs-config that can house simple component configuration as a JSON string. When an element has data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the separate data attributes will override values given on data-bs-config. In addition, existing data attributes are able to house JSON values like data-bs-delay='{"show":0,"hide":150}'.

The final configuration object is the merged result of data-bs-config, data-bs-, and js object where the latest given key-value overrides the others.

Name	Type	Default	Description
`autoClose`	boolean, string	`true`	Configure the auto close behavior of the dropdown: `true` - the dropdown will be closed by clicking outside or inside the dropdown menu. `false` - the dropdown will be closed by clicking the toggle button and manually calling `hide` or `toggle` method. (Also will not be closed by pressing `Esc` key) `'inside'` - the dropdown will be closed (only) by clicking inside the dropdown menu. `'outside'` - the dropdown will be closed (only) by clicking outside the dropdown menu. Note: the dropdown can always be closed with the `Esc` key.
`boundary`	string, element	`'clippingParents'`	Overflow constraint boundary of the dropdown menu (applies only to the shift middleware). By default it's `clippingParents` and can accept an HTMLElement reference (via JavaScript only). For more information refer to Floating UI's shift docs.
`display`	string	`'dynamic'`	By default, we use Floating UI for dynamic positioning. Disable this with `static`.
`offset`	array, string, function	`[0, 2]`	Offset of the dropdown relative to its target. You can pass a string in data attributes with comma separated values like: `data-bs-offset="10,20"`. When a function is used to determine the offset, it is called with an object containing the placement, the reference, and floating rects as its first argument. The triggering element DOM node is passed as the second argument. The function must return an array with two numbers: [skidding, distance]. For more information refer to Floating UI's offset docs.
`floatingConfig`	null, object, function	`null`	To change Bootstrap's default Floating UI config, see Floating UI's configuration. When a function is used to create the Floating UI configuration, it's called with an object that contains the Bootstrap's default Floating UI configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Floating UI.
`placement`	string	`'bottom-start'`	Placement of the dropdown menu. Physical placements: `'top'`, `'bottom'`, `'left'`, `'right'`. Logical placements (RTL-aware): `'start'`, `'end'`. All support alignment modifiers: `-start`, `-end`. Supports responsive prefixes like `'bottom-start md:end'`.
`reference`	string, element, object	`'toggle'`	Reference element of the dropdown menu. Accepts the values of `'toggle'`, `'parent'`, an HTMLElement reference or an object providing `getBoundingClientRect`. For more information refer to Floating UI's virtual elements docs.
`submenuTrigger`	string	`'both'`	How submenus are triggered. Use `'click'` for click only, `'hover'` for hover only, or `'both'` for both click and hover activation.
`submenuDelay`	number	`100`	Delay in milliseconds before closing a submenu when the mouse leaves. Provides a grace period for diagonal mouse movement toward the submenu.

Using function with `floatingConfig`

JavaScript

const dropdown = new bootstrap.Dropdown(element, {
  floatingConfig(defaultBsFloatingConfig) {
    // const newFloatingConfig = {...}
    // use defaultBsFloatingConfig if needed...
    // return newFloatingConfig
  }
})

Methods

Method	Description
`dispose`	Destroys an element’s dropdown. (Removes stored data on the DOM element)
`getInstance`	Static method which allows you to get the dropdown instance associated to a DOM element, you can use it like this: `bootstrap.Dropdown.getInstance(element)`.
`getOrCreateInstance`	Static method which returns a dropdown instance associated to a DOM element or create a new one in case it wasn’t initialized. You can use it like this: `bootstrap.Dropdown.getOrCreateInstance(element)`.
`hide`	Hides the dropdown menu of a given navbar or tabbed navigation.
`show`	Shows the dropdown menu of a given navbar or tabbed navigation.
`toggle`	Toggles the dropdown menu of a given navbar or tabbed navigation.
`update`	Updates the position of an element’s dropdown.

Events

All dropdown events are fired at the toggling element and then bubbled up. So you can also add event listeners on the .dropdown-menu’s parent element. hide.bs.dropdown and hidden.bs.dropdown events have a clickEvent property (only when the original Event type is click) that contains an Event Object for the click event.

Event type	Description
`hide.bs.dropdown`	Fires immediately when the `hide` instance method has been called.
`hidden.bs.dropdown`	Fired when the dropdown has finished being hidden from the user and CSS transitions have completed.
`show.bs.dropdown`	Fires immediately when the `show` instance method is called.
`shown.bs.dropdown`	Fired when the dropdown has been made visible to the user and CSS transitions have completed.

JavaScript

const myDropdown = document.getElementById('myDropdown')
myDropdown.addEventListener('show.bs.dropdown', event => {
  // do something...
})

Dropdown

Overview

Examples

Single button

Split button

Dark dropdowns

Placement

Responsive

Menu items

Active

Disabled

Menu content

Headers

Dividers

Text

Forms

Submenus

Nested submenus

Multiple submenus

Auto close behavior

Accessibility

Keyboard navigation

CSS

Variables

Sass variables

Sass mixins

Usage

Via data attributes

Via JavaScript

Dependencies

Options

Using function with `floatingConfig`

Methods

Events

Dropdown

Overview

Examples

Single button

Split button

Dark dropdowns

Placement

Responsive

Menu items

Active

Disabled

Menu content

Headers

Dropdown header

Dividers

Text

Forms

Submenus

Nested submenus

Multiple submenus

Dropdown options

Auto close behavior

Accessibility

Keyboard navigation

CSS

Variables

Sass variables

Sass mixins

Usage

Via data attributes

Via JavaScript

Dependencies

Options

Using function with floatingConfig

Methods

Events

Using function with `floatingConfig`