Dropdowns

The Dropdowns component provides toggleable, accessible menus with simple classes and JavaScript for navigation or actions.

Dropdowns use the Popper library for dynamic positioning and viewport detection. Include popper.min.js before Hummingbird’s JavaScript, or use hummingbird.bundle.min.js / hummingbird.bundle.js, which include Popper. See the dependencies section for more details.

Dropdown components integrate Bootstrap's JavaScript plugins for interactivity, paired with custom styling for a unique and consistent user experience.

Class Name	Type	Description
dropdown	Component	Dropdown menu
dropup	Component	Dropup menu
dropstart	Component	Dropstart menu
dropend	Component	Dropend menu
dropdown-menu	Inner	Menu container
dropdown-menu-start	Inner	Align start
dropdown-menu-end	Inner	Align end
dropdown-header	Inner	Menu header
dropdown-item	Inner	Menu item
dropdown-item-text	Inner	Text item
dropdown-divider	Inner	Menu divider
dropup-center	Modifier	Centered dropup
dropdown-center	Modifier	Centered dropdown
dropstart-center	Modifier	Centered dropstart
dropend-center	Modifier	Centered dropend

Single button

Any .btn can be converted into a dropdown toggle with the appropriate markup. Example using a <button> element:

HTML

<div class="dropdown">
  <button class="btn btn-subtle-neutral" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropdown</button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
  </ul>
</div>

While <button> is the recommended element for a dropdown toggle, an <a> element may be used when necessary. In such cases, add role="button" to convey its purpose correctly to assistive technologies like screen readers.

HTML

<div class="dropdown">
  <a class="btn btn-subtle-neutral" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">Dropdown link</a>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
  </ul>
</div>

Directions

To center a dropdown menu below its toggle, add the .dropdown-center class to the parent element.

HTML

<div class="dropdown-center">
  <button class="btn btn-subtle-neutral" type="button" data-bs-toggle="dropdown" aria-expanded="false">Centered Dropdown</button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
  </ul>
</div>

Dropup

To display a dropdown menu above its toggle, add the .dropup class to the parent element.

HTML

<div class="dropup">
  <button class="btn btn-subtle-neutral" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropup</button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
  </ul>
</div>

Dropup centered

To center a dropup menu above its toggle, add the .dropup-center class to the parent element.

HTML

<div class="dropup-center dropup">
  <button class="btn btn-subtle-neutral" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropup Centered</button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
  </ul>
</div>

Dropend

To display a dropdown menu to the right of its toggle, add the .dropend class to the parent element.

HTML

<div class="dropend">
  <button class="btn btn-subtle-neutral" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropend</button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
  </ul>
</div>

Dropstart

To display a dropdown menu to the left of its toggle, add the .dropstart class to the parent element.

HTML

<div class="dropstart">
  <button class="btn btn-subtle-neutral" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropstart</button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
  </ul>
</div>

HTML

<div class="dropdown">
  <button class="btn btn-subtle-neutral" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown
    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"><path fill="currentColor" fill-rule="evenodd" d="M7 9a1 1 0 0 0-.707 1.707l5 5a1 1 0 0 0 1.414 0l5-5A1 1 0 0 0 17 9z" clip-rule="evenodd"/></svg>
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
  </ul>
</div>

By default, dropdown menus are positioned 100% from the top and aligned to the left of the parent. Use directional .drop* classes or modifier classes to adjust this.

Add .dropdown-menu-end to .dropdown-menu to right-align the menu.

HTML

<div class="btn-group">
  <button type="button" class="btn btn-subtle-neutral" data-bs-toggle="dropdown" aria-expanded="false">Right-aligned menu example</button>
  <ul class="dropdown-menu dropdown-menu-end">
    <li><button class="dropdown-item" type="button">Profile</button></li>
    <li><button class="dropdown-item" type="button">My Account</button></li>
    <li><button class="dropdown-item" type="button">Dashboard</button></li>
  </ul>
</div>

Responsive alignment

For responsive alignment, disable dynamic positioning by adding the data-bs-display="static" attribute and use the responsive variation classes.

To right align a dropdown menu at a specific breakpoint or larger, add .dropdown-menu{-sm|-md|-lg|-xl|-xxl}-end.

HTML

<div class="btn-group">
  <button type="button" class="btn btn-subtle-neutral" data-bs-toggle="dropdown" aria-expanded="false">Left-aligned but right aligned when large screen</button>
  <ul class="dropdown-menu lg:dropdown-menu-end">
    <li><button class="dropdown-item" type="button">Profile</button></li>
    <li><button class="dropdown-item" type="button">My Account</button></li>
    <li><button class="dropdown-item" type="button">Dashboard</button></li>
  </ul>
</div>

Add a header to label groups of actions within any dropdown menu.

HTML

<div class="dropdown">
  <button class="btn btn-subtle-neutral" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropdown</button>
  <ul class="dropdown-menu">
    <li><h6 class="dropdown-header">Dropdown header</h6></li>
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
  </ul>
</div>

Use a divider to separate groups of related menu items.

HTML

<div class="dropdown">
  <button class="btn btn-subtle-neutral" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropdown</button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
    <li><hr class="dropdown-divider" /></li>
    <li><a class="dropdown-item" href="#">Sign Out</a></li>
  </ul>
</div>

Text

Freeform text can be placed inside a dropdown menu. Use spacing utilities as needed, and apply sizing utilities to constrain the menu width if required.

HTML

<div class="dropdown">
  <button class="btn btn-subtle-neutral" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropdown</button>
  <div class="dropdown-menu p-4 w-60">
    <p class="mb-0">Some example text that’s free-flowing within the dropdown menu.</p>
  </div>
</div>

Use data-bs-offset or data-bs-reference to adjust the position of a dropdown menu.

HTML

<div class="dropdown">
  <button type="button" class="btn btn-subtle-neutral" data-bs-toggle="dropdown" aria-expanded="false" data-bs-offset="10,20">Offset</button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
  </ul>
</div>
<div class='dropdown flex gap-1'>
  <button type="button" class="btn btn-subtle-neutral">Reference</button>
  <button class='btn btn-subtle-neutral btn-square' type="button" data-bs-toggle="dropdown" aria-expanded="false" data-bs-reference="parent">
    <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24"><path fill="currentColor" d="M12 14.975q-.2 0-.375-.062T11.3 14.7l-4.6-4.6q-.275-.275-.275-.7t.275-.7t.7-.275t.7.275l3.9 3.9l3.9-3.9q.275-.275.7-.275t.7.275t.275.7t-.275.7l-4.6 4.6q-.15.15-.325.213t-.375.062" stroke-width="0.5" stroke="currentColor"/></svg>
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Profile</a></li>
    <li><a class="dropdown-item" href="#">My Account</a></li>
    <li><a class="dropdown-item" href="#">Dashboard</a></li>
    <li><hr class="dropdown-divider" /></li>
    <li><a class="dropdown-item" href="#">Sign Out</a></li>
  </ul>
</div>

Auto close behavior

By default, a dropdown menu closes when clicked inside or outside. Control this behavior with the autoClose option.

HTML

<div class="relative">
  <button class="btn btn-subtle-neutral" 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="relative">
  <button class="btn btn-subtle-neutral" 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="relative">
  <button class="btn btn-subtle-neutral" 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="relative">
  <button class="btn btn-subtle-neutral" 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>

CSS variables

The dropdown component is built using a set of CSS variables. These variables provide flexibility for customizing styles.

.dropdown-menu {
  --dropdown-zindex: 1000;
  --dropdown-bg: var(--background-color-default);
  --dropdown-spacer: --spacing(0.5);
  --dropdown-min-width: 10rem;
  --dropdown-padding-x: 0;
  --dropdown-padding-y: --spacing(2);
  --dropdown-font-size: var(--text-sm);
  --dropdown-border-width: 1px;
  --dropdown-border-color: transparent;
  --dropdown-box-shadow: var(--shadow-xl);
  --dropdown-border-radius: var(--radius-lg);
  --dropdown-link-color: var(--text-color-default);
  --dropdown-link-hover-color: var(--text-color-default);
  --dropdown-link-hover-bg: var(--background-color-subtle);
  --dropdown-link-disabled-color: var(--color-disabled-color);
  --dropdown-link-active-color: var(--color-primary);
  --dropdown-link-active-bg: var(--color-primary-lighter);
  --dropdown-item-padding-x: --spacing(4);
  --dropdown-item-padding-y: --spacing(1.5);
  --dropdown-divider-bg: var(--border-color-base);
  --dropdown-divider-margin-y: --spacing(2);
  --dropdown-header-padding-y: --spacing(2);
  --dropdown-header-padding-x: --spacing(4);
  --dropdown-header-color: var(--text-color-muted);
  --dropdown-header-font-size: var(--text-base);
}

Usage

Through either data attributes or JavaScript, the dropdown plugin manages hidden content (dropdown menus) by toggling the .show class on the parent .dropdown-menu. The data-bs-toggle="dropdown" attribute is essential for closing dropdown menus at an application level, making its consistent use advisable.

On touch-enabled devices, opening a dropdown introduces temporary, empty mouseover handlers to the immediate children of the <body> element. This measure addresses an iOS event delegation quirk that would otherwise prevent a tap outside the dropdown from triggering the code responsible for closing it. Once the dropdown is closed, these additional mouseover handlers are removed.

Via data attributes

To toggle a dropdown, add data-bs-toggle="dropdown" to a link or button:

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

Via JavaScript

Use JavaScript in the familiar pattern of Bootstrap’s plugins with full additional TypeScript Support.

Dropdowns require data-bs-toggle="dropdown" on their trigger element, regardless of whether they are called via JavaScript or the data-api.

Dropdowns can be called via JavaScript as follows:

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

Options

Options can be provided through data attributes or via JavaScript. When using data-bs-attributes, append the option’s name (e.g., data-bs-animation="{value}"). It is crucial to convert “camelCase” option names to “kebab-case” when passing options via data attributes. For instance, use data-bs-custom-class="beautifier" rather than data-bs-customClass="beautifier".

Dropdown component support data-bs-config data attribute. This attribute can contain simple component configurations as a JSON string. If an element has both data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456, as separate data attributes override values provided within data-bs-config. Additionally, existing data attributes can also house JSON values, such as data-bs-delay='{"show":0,"hide":150}'.

The ultimate configuration object results from merging data-bs-config, individual data-bs-attributes, and JavaScript objects, where the latest provided key-value pair takes precedence over others.

Name	Type	Default	Description
`autoClose`	boolean \| string	`true`	Configures the dropdown’s auto-close behavior: `true` – The dropdown will close when clicking either outside or inside the dropdown menu. `false` – The dropdown will close only by clicking the toggle button or by manually calling the hide or toggle method. (It will also not close by pressing the Esc key.) `‘inside’` – The dropdown will close only by clicking inside the dropdown menu. `‘outside’` – The dropdown will close only by clicking outside the dropdown menu. Note: The dropdown can always be closed with the Esc key.
`boundary`	string \| element	`'clippingParents'`	Defines the overflow constraint boundary for the dropdown menu (this applies only to Popper’s preventOverflow modifier). By default, it is `clippingParents` and can accept an HTMLElement reference (via JavaScript only). For more information, refer to Popper’s detectOverflow docs.
`display`	string	`'dynamic'`	By default, Popper is used for dynamic positioning. This can be disabled by setting the value to `static`.
`offset`	array \| string \| function	`[0, 2]`	Determines the offset of the dropdown relative to its target. A string with comma-separated values, such as `data-bs-offset="10,20"`, can be passed in data attributes. When a function is used to define the offset, it receives an object (containing the Popper placement, reference, and Popper rects) as its first argument, and the triggering element’s DOM node as the second. The function must return an array with two numbers: skidding and distance. For more information, refer to Popper’s offset documentation.
`popperConfig`	null \| object \| function	`null`	Allows modification of Bootstrap’s default Popper configuration. Refer to Popper’s configuration documentation. When a function is used to create the Popper configuration, it is called with an object containing Bootstrap’s default Popper configuration. This facilitates using and merging the default configuration with custom settings. The function must return a configuration object for Popper.
`reference`	string \| element \| object	`'toggle'`	Specifies the reference element for the dropdown menu. It accepts values of ‘toggle’, ‘parent’, an HTMLElement reference, or an object that provides getBoundingClientRect. For further details, refer to Popper’s constructor and virtual element documentation.

Using function with popperConfig:

const dropdown = new hummingbird.Dropdown(element, {
  popperConfig(defaultBsPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

Methods

Method	Description
`dispose`	Destroys an element’s dropdown functionality, removing stored data on the DOM element.
`getInstance`	A static method allowing retrieval of the dropdown instance associated with a DOM element. Usage: `hummingbird.Dropdown.getInstance(element)`.
`getOrCreateInstance`	A static method that returns an existing dropdown instance for a DOM element or creates a new one if it has not been initialized. Usage: `hummingbird.Dropdown.getOrCreateInstance(element)`.
`hide`	Conceals the dropdown menu within a given navbar or tabbed navigation.
`show`	Displays the dropdown menu within a given navbar or tabbed navigation.
`toggle`	Toggles the dropdown menu within a given navbar or tabbed navigation.
`update`	Updates the position of an element’s dropdown.

Events

All dropdown events are dispatched at the toggling element and then propagate upwards (bubble). Therefore, event listeners can also be added to the .dropdown-menu’s parent element. The hide.bs.dropdown and hidden.bs.dropdown events include a clickEvent property (only when the original Event type is click) which contains an Event object for the click event.

Method	Description
`hide.bs.dropdown`	This event fires immediately when the `hide` instance method has been called.
`hidden.bs.dropdown`	This event fires when the dropdown has finished being hidden from the user and CSS transitions have completed.
`show.bs.dropdown`	This event fires immediately when the `show` instance method is called.
`shown.bs.dropdown`	This event fires when the dropdown has been made visible to the user and CSS transitions have completed.

Example event listener:

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

hummingbird

Getting Started

Customize

Layout & content

Forms

Components

Dropdowns

Single button

Directions

Dropup

Dropup centered

Dropend

Dropstart

Menu alignment

Responsive alignment

Menu header

Menu divider

Text

Auto close behavior

CSS variables

Usage

Via data attributes

Via JavaScript

Options

Methods

Events

hummingbird

Getting Started

Customize

Layout & content

Forms

Components

Dropdowns

Single button

Directions

Centered dropdown

Dropup

Dropup centered

Dropend

Dropstart

Dropdown with icon

Menu alignment

Responsive alignment

Menu header

Dropdown header

Menu divider

Text

Dropdown options

Auto close behavior

CSS variables

Usage

Via data attributes

Via JavaScript

Options

Methods

Events