bootstrap_ref_js_dropdown

Dropdowns are toggleable, contextual overlays for displaying lists of links and more. They are made interactive with the Bootstrap dropdown JavaScript plugin, which relies on Popper.js for positioning.

For a step-by-step tutorial on creating Dropdowns, refer to our Bootstrap Dropdowns Tutorial.

Class / Element	Description
.dropdown	The main wrapper for the dropdown component.
.dropdown-toggle	Added to the button/link that triggers the dropdown menu.
.dropdown-menu	The `<ul>` element that contains the dropdown items.
.dropdown-item	Class for `<a>` or `<button>` elements within the `.dropdown-menu`.
.dropdown-divider	An `<hr>` tag with this class used to separate groups of items.
.dropdown-header	A `<h6>` (often inside an `<li>`) with this class to label sections.
.dropdown-menu-end	Aligns the dropdown menu to the right (end) of the toggle.
.dropdown-menu-{breakpoint}-start/end	Responsive alignment for the dropdown menu.
.dropup, .dropend, .dropstart	Classes on the `.dropdown` parent to change menu direction.
.disabled	Added to a `.dropdown-item` to disable it.

Usage via Data Attributes

Activate a dropdown without writing any JavaScript by simply adding data-bs-toggle="dropdown" to a link or button. An aria-expanded attribute is also recommended.

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButtonSimple" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown button
  </button>
  <ul class="dropdown-menu" aria-labelledby="dropdownMenuButtonSimple">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
  </ul>
</div>

Usage via JavaScript

You can also initialize dropdowns manually using JavaScript:

var dropdownElement = document.getElementById('myDropdownToggle');
var dropdownInstance = new bootstrap.Dropdown(dropdownElement, {
  // optional options object
});

// To initialize all dropdowns on a page:
const dropdownElementList = document.querySelectorAll('.dropdown-toggle');
const dropdownList = [...dropdownElementList].map(dropdownToggleEl => new bootstrap.Dropdown(dropdownToggleEl));

Note: If initializing via JavaScript, data-bs-toggle="dropdown" is still typically used on the trigger element for convenience, but the JS constructor takes precedence.

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-bs-, like data-bs-offset="[10,20]".

Name	Default	Data attribute	Description
offset	[0, 2]	`data-bs-offset`	Offset of the dropdown relative to its target. Can be a string like ‘10,20’ or an array `[skidding, distance]`.
boundary	’clippingParents’	`data-bs-boundary`	Defines the overflow boundary of the dropdown. Accepts ‘clippingParents’, ‘viewport’, or an HTMLElement reference.
reference	’toggle’	`data-bs-reference`	Reference element for the dropdown’s position. Accepts ‘toggle’, ‘parent’, or an HTMLElement reference.
display	’dynamic’	`data-bs-display`	By default, we use Popper for dynamic positioning. Disable this with `static`.
popperConfig	null	`data-bs-popper-config`	To change Bootstrap’s default Popper config, see Popper’s configuration. Can be an object or a function.

Dropdown methods are called on the dropdown instance.

Method
Description
Example


`toggle()`
Toggles the dropdown menu of a given navbar or tabbed navigation.
`myDropdownInstance.toggle()`


`show()`
Shows the dropdown menu of a given navbar or tabbed navigation.
`myDropdownInstance.show()`


`hide()`
Hides the dropdown menu of a given navbar or tabbed navigation.
`myDropdownInstance.hide()`


`update()`
Updates the position of an element’s dropdown.
`myDropdownInstance.update()`


`dispose()`
Destroys an element’s dropdown. (Removes stored data on the DOM element)
`myDropdownInstance.dispose()`


`getInstance(element)`
Static method which allows you to get the dropdown instance associated with a DOM element.
`bootstrap.Dropdown.getInstance(myDropdownToggleElement)`


`getOrCreateInstance(element, config?)`
Static method which allows you to get the dropdown instance associated with a DOM element, or create a new one in case it wasn’t initialized.
`bootstrap.Dropdown.getOrCreateInstance(myDropdownToggleElement, { offset: [0,10] })`

Bootstrap’s dropdown plugin exposes a few events for hooking into dropdown functionality.

Event Type
Description


`show.bs.dropdown`
This event fires immediately when the show instance method is called. The dropdown toggle element is available as the `relatedTarget` property of the event.


`shown.bs.dropdown`
This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions to complete). The dropdown toggle element is available as the `relatedTarget` property of the event.


`hide.bs.dropdown`
This event is fired immediately when the hide instance method has been called. The dropdown toggle element is available as the `relatedTarget` property of the event.


`hidden.bs.dropdown`
This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions to complete). The dropdown toggle element is available as the `relatedTarget` property of the event.


Example of using an event:

```javascript
const myDropdownEl = document.getElementById('someDropdown');
myDropdownEl.addEventListener('shown.bs.dropdown', function (event) {
  // event.relatedTarget is the triggering Toggler element
  console.log('Dropdown shown, triggered by: ', event.relatedTarget.textContent);
  // Do something when the dropdown is shown
});

bootstrap_ref_js_dropdown

Bootstrap JS Dropdown Reference

JS Dropdown (dropdown.js)

The Dropdown Plugin Classes & HTML Structure

Usage via Data Attributes

Usage via JavaScript

Dropdown Options

Dropdown Methods

Dropdown Events