Dropdowns

Overview #

A few important things to know when using the dropdown plugin:

• Dropdowns rely on the third party library Popper (opens in new tab) for positioning. You must include popper.js before bootstrap.js, or use one bootstrap.bundle.js which contains Popper.
• Dropdown menus are toggled by clicking, not hovering.

You can create dropdowns by wrapping the trigger and menu (.dropdown-menu) inside a <div> with the .dropdown class, or another element that declares position: relative. The trigger should have the data-bs-toggle="dropdown" attribute, along with the .dropdown-toggle class (which adds a visual caret). Ideally, you should use a <button> element as the dropdown trigger, but the plugin will work with <a> elements as well.

<!-- First dropdown -->
<div class="dropdown">
  <button class="btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Button
  </button>
  <ul class="dropdown-menu">
    <li><h6 class="dropdown-header">Header</h6></li>
    <li><a href="#" class="dropdown-item active" aria-current="true">Dropdown link 1</a></li>
    <li><a href="#" class="dropdown-item">Dropdown link 2</a></li>
    <li><a href="#" class="dropdown-item">Dropdown link 3</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item disabled">Dropdown link 4</a></li>
  </ul>
</div>

<!-- Second dropdown -->
<div class="dropdown">
  <a href="#" class="btn btn-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">
    Link
  </a>
  <ul class="dropdown-menu">
    <li><h6 class="dropdown-header">Header</h6></li>
    <li><button type="button" class="dropdown-item active" aria-current="true">Dropdown button 1</a></li>
    <li><button type="button" class="dropdown-item">Dropdown button 2</a></li>
    <li><button type="button" class="dropdown-item disabled" disabled>Dropdown button 3</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><span class="dropdown-item-text">Dropdown text</span></li>
  </ul>
</div>

A few more things about dropdowns:

• You can use <a> or <button> elements as the dropdown items (.dropdown-item).
• Add .active to items in the dropdown to style them as active. 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.
• Add .disabled to items in the dropdown to style them as disabled. Omit the href for links, and for buttons, add the disabled attribute along with the class.
• Headers (.dropdown-header), dividers (.dropdown-divider), and text (.dropdown-item-text) are also supported as shown above.

Accessibility #

The WAI ARIA (opens in new tab) standard defines an actual role="menu" widget (opens in new tab), 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.

Halfmoon'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, Halfmoon 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.

However, Halfmoon does add built-in support for most standard keyboard menu interactions, such as the ability to move through individual .dropdown-item elements using the cursor keys and close the menu with the esc key.

Split button #

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.

<div class="btn-group">
  <button type="button" class="btn btn-primary">Button</button>
  <button type="button" class="btn btn-primary 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><h6 class="dropdown-header">Header</h6></li>
    <li><a href="#" class="dropdown-item active" aria-current="true">Dropdown link 1</a></li>
    <li><a href="#" class="dropdown-item">Dropdown link 2</a></li>
    <li><a href="#" class="dropdown-item">Dropdown link 3</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item disabled">Dropdown link 4</a></li>
  </ul>
</div>

Menu content and form #

Put a form within a dropdown menu, or make it into a dropdown menu, and use margin or padding utilities to give it the negative space you require. Moreover, you can also place any freeform text within a dropdown menu with text utilities (along with the aforementioned spacing utilities). Note that you'll likely need additional sizing styles to constrain the menu width.

<div class="dropdown-center">
  <button class="btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false" data-bs-auto-close="outside">
    Sign in
  </button>
  <div class="dropdown-menu specific-w-300">
    <form class="p-3">
      <div class="mb-2">
        <label for="email" class="form-label">Email address</label>
        <input type="email" class="form-control" id="email" placeholder="Email address">
      </div>
      <div class="mb-3">
        <label for="password" class="form-label">Password</label>
        <input type="password" class="form-control" id="password" placeholder="Password">
      </div>
      <div class="mb-3 pb-3 border-bottom">
        <button type="submit" class="btn btn-primary w-100">Sign in</button>
      </div>
      <div class="text-center text-body-secondary">
        Don't have an account? <a href="#">Sign up</a>
      </div>
    </form>
  </div>
</div>

Directions #

Multiple directions are supported for dropdowns by adding the appropriate class to the parent element. Directions are flipped in RTL mode, so for example, .dropstart will appear on the right side.

Directions Centered #

Make the dropdown menu centered below the toggle with .dropdown-center on the parent element.

<!-- Centered dropdown -->
<div class="dropdown-center">
  <button class="btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Button
  </button>
  <ul class="dropdown-menu">...</ul>
</div>

<div class="dropdown-center">
  <a href="#" class="btn btn-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">
    Link
  </a>
  <ul class="dropdown-menu">...</ul>
</div>

Directions Dropup #

Trigger dropdown menus above elements by adding .dropup to the parent element.

<!-- Dropup -->
<div class="dropup">
  <button class="btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Button
  </button>
  <ul class="dropdown-menu">...</ul>
</div>

<div class="dropup">
  <a href="#" class="btn btn-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">
    Link
  </a>
  <ul class="dropdown-menu">...</ul>
</div>

Directions Dropup centered #

Make the dropup menu centered above the toggle with .dropup-center (along with the .dropup class) on the parent element.

<!-- Centered dropup -->
<div class="dropup dropup-center">
  <button class="btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Button
  </button>
  <ul class="dropdown-menu">...</ul>
</div>

<div class="dropup dropup-center">
  <a href="#" class="btn btn-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">
    Link
  </a>
  <ul class="dropdown-menu">...</ul>
</div>

Directions Dropend #

Trigger dropdown menus at the right of the elements by adding .dropend to the parent element.

<!-- Dropend -->
<div class="dropend">
  <button class="btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Button
  </button>
  <ul class="dropdown-menu">...</ul>
</div>

<div class="dropend">
  <a href="#" class="btn btn-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">
    Link
  </a>
  <ul class="dropdown-menu">...</ul>
</div>

Directions Dropstart #

Trigger dropdown menus at the left of the elements by adding .dropstart to the parent element.

<!-- Dropstart -->
<div class="dropstart">
  <button class="btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Button
  </button>
  <ul class="dropdown-menu">...</ul>
</div>

<div class="dropstart">
  <a href="#" class="btn btn-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">
    Link
  </a>
  <ul class="dropdown-menu">...</ul>
</div>

Menu alignment #

By default, a dropdown menu is automatically positioned 100% from the top and along the left side of its parent. You can change this alignment by adding the following classes to the .dropdown-menu:

• .dropdown-menu-start / .dropdown-menu-{breakpoint}-start — aligns menu to the left
• .dropdown-menu-end / .dropdown-menu-{breakpoint}-end — aligns menu to the right

The alignment is flipped in RTL mode, so for example, .dropdown-menu-end would align the menu to the left (instead of right). The {breakpoint} can be sm, md, lg, xl, or xxl. If the breakpoint is not provided, the element will be affected on all screen sizes (including on extra small screens). On the other hand, if it is provided, the element will be affected only for that breakpoint and up.

<!-- Responsive dropdown menu -->
<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false" data-bs-display="static">
    Responsive
  </button>
  <ul class="dropdown-menu dropdown-menu-start dropdown-menu-lg-end">...</ul>
</div>

<!-- Right-aligned dropdown menu -->
<div class="dropdown">
  <button class="btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Right
  </button>
  <ul class="dropdown-menu dropdown-menu-end">...</ul>
</div>

In the above example, the first dropdown menu is aligned to the left by default, but on large screens and up, it will be aligned to the right. The second menu will always be aligned to the right. Please note, these classes are only supported for .dropdown, .dropdown-center, .dropup, and .dropup-center.

Dropdown options #

Use data-bs-offset="{x, y}" or data-bs-reference to change the location of the dropdown menu.

<!-- Custom offset -->
<div class="dropdown">
  <button class="btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false" data-bs-offset="0, 10">
    Button
  </button>
  <ul class="dropdown-menu">...</ul>
</div>

<!-- Reference set to parent -->
<div class="btn-group">
  <button type="button" class="btn btn-primary">Reference</button>
  <button type="button" class="btn btn-primary 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">...</ul>
</div>

Dropdown options 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, e.g., using the data-bs-auto-close="{behavior}" attribute, where {behavior} can be true (default), inside, outside, or false.

<!-- Closed when clicked inside menu -->
<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false" data-bs-auto-close="inside">
    Inside
  </button>
  <ul class="dropdown-menu">...</ul>
</div>

<!-- Closed when clicked outside menu -->
<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false" data-bs-auto-close="outside">
    Outside
  </button>
  <ul class="dropdown-menu">...</ul>
</div>

<!-- Closed only when trigger is clicked -->
<div class="dropdown">
  <button class="btn btn-button dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false" data-bs-auto-close="false">
    On this
  </button>
  <ul class="dropdown-menu">...</ul>
</div>

JavaScript usage #

The examples on this page use data-bs-* attributes for functionality, which is usually enough to cover a majority of use-cases. You can read about options, methods, events, and more in the official Bootstrap documentation.

Dropdowns - Bootstrap
Continue reading on the offical documentation website