` elements as dropdown items.
```html
Dropdown
```
You can also create non-interactive dropdown items with `.dropdown-item-text`. Feel free to style further with custom CSS or text utilities.
```html
```
### Active
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.
```html
```
### Disabled
Add `.disabled` to items in the dropdown to **style them as disabled**.
```html
```
## Menu alignment
By default, a dropdown menu is automatically positioned 100% from the top and along the left side of its parent. Add `.dropdown-menu-end` to a `.dropdown-menu` to right align the dropdown menu.
> **Heads up!** Dropdowns are positioned thanks to Floating UI except when they are contained in a navbar.
```html
Right-aligned menu example
```
### Responsive alignment
Alignment that changes with the viewport is a responsive [placement](#placement-option): `data-coreui-placement="bottom-start lg:bottom-end"` aligns the menu left and switches to right from `lg` up. It works with dynamic positioning and, because the plugin writes the resolved placement onto the menu, with `data-coreui-display="static"` and inside a navbar too.
```html
Left-aligned but right aligned when large screen
```
```html
Right-aligned but left aligned when large screen
```
The v5 classes `.dropdown-menu{-sm|-md|-lg|-xl|-2xl}{-start|-end}` ship in [`coreui-legacy.css`](https://coreui.io/bootstrap/docs/getting-started/install/#v5-compatibility-css) for markup that still uses them.
### Alignment options
Taking most of the options shown above, here's a small kitchen sink demo of various dropdown alignment options in one place.
```html
Dropdown
Right-aligned menu
Left-aligned, right-aligned lg
Right-aligned, left-aligned lg
Dropstart
Dropend
Dropup
```
## Menu content
### Headers
Add a header to label sections of actions in any dropdown menu.
```html
```
### Dividers
Separate groups of related menu items with a divider.
```html
```
### Text
Place any freeform text within a dropdown menu with text and use [spacing utilities](https://coreui.io/bootstrap/docs/utilities/margin/). Note that you'll likely need additional sizing styles to constrain the menu width.
```html
```
### Forms
Put a form within a dropdown menu, or make it into a dropdown menu, and use [margin or padding utilities](https://coreui.io/bootstrap/docs/utilities/margin/) to give it the negative space you require.
```html
```
```html
Dropdown form
```
## Dropdown options
Use `data-coreui-offset` or `data-coreui-reference` to change the location of the dropdown.
```html
Offset
Reference
Toggle Dropdown
```
### 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
Default dropdown
Clickable inside
Clickable outside
Manual close
```
## 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-coreui-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 `` element. This admittedly ugly hack is necessary to work around a [quirk in iOS' event delegation](https://www.quirksmode.org/blog/archives/2014/02/mouse_event_bub.html), 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-coreui-toggle="dropdown"` to a link or button to toggle a dropdown.
```html
Dropdown trigger
```
### Via JavaScript
Call the dropdowns via JavaScript:
```js
const dropdownElementList = document.querySelectorAll('.dropdown-toggle')
const dropdownList = [...dropdownElementList].map(dropdownToggleEl => new coreui.Dropdown(dropdownToggleEl))
```
> ##### `data-coreui-toggle="dropdown"` still required
>
> Regardless of whether you call your dropdown via JavaScript or instead use the data-api, `data-coreui-toggle="dropdown"` is always required to be present on the dropdown's trigger element.
### Options
Options can be passed using data attributes or JavaScript. To do this, append an option name to `data-coreui-`, such as `data-coreui-animation="{value}"`. Remember to convert the case of the option name from "_camelCase_" to "_kebab-case_" when using data attributes. For instance, you should write `data-coreui-custom-class="beautifier"` rather than `data-coreui-customClass="beautifier"`.
Starting with CoreUI 4.2.6, all components support an **experimental** reserved data attribute named `data-coreui-config`, which can contain simple component configurations as a JSON string. If an element has attributes `data-coreui-config='{"delay":50, "title":689}'` and `data-coreui-title="Custom Title"`, then the final value for `title` will be `Custom Title`, as the standard data attributes will take precedence over values specified in `data-coreui-config`. Moreover, existing data attributes can also hold JSON values like `data-coreui-delay='{"show":50, "hide":250}'`.
| 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. ESC key |
| `boundary` | string, element | `'clippingParents'` | Overflow constraint boundary of the dropdown menu. By default it's `clippingParents` and can accept an HTMLElement reference (via JavaScript only). For more information refer to Floating UI's [detectOverflow docs](https://floating-ui.com/docs/detectOverflow/#boundary). |
| `container` | string, element, boolean | `false` | Appends the dropdown menu to a specific element when shown. Use `'body'` or `true` to append to the document body, which helps escape containers with `overflow: hidden`. The menu is moved back to its original position when hidden. Inside a modal dialog it goes into the dialog instead, because the rest of the page is inert. |
| `display` | string | `'dynamic'` | By default, we use Floating UI for dynamic positioning. Disable this with `static`. |
| `floatingConfig` | null, object, function | `null` | To change CoreUI's default Floating UI config, see Floating UI's [computePosition docs](https://floating-ui.com/docs/computePosition/#options). When a function is used to create the configuration, it's called with an object that contains the default configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Floating UI. |
| `menu` | null, element | `null` | The `.dropdown-menu` to open (JavaScript only). By default the plugin takes the `.dropdown-menu` next to the toggle, or the one inside the toggle's wrapper. |
| `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-coreui-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 (along the edge) and distance (away from it). For more information refer to Floating UI's [offset docs](https://floating-ui.com/docs/offset/#options). |
| `placement` | null, string | `null` | Where the menu opens, in the [Menu](https://coreui.io/bootstrap/docs/components/menu/#placement) syntax: physical (`'top'`, `'bottom'`, `'left'`, `'right'`) or logical (`'start'`, `'end'`) placements with `-start`/`-end` alignment, and breakpoint prefixes such as `'bottom-start md:top-end'`. `null` derives the placement from the direction classes (`.dropup`, `.dropend`, `.dropstart`, `.dropdown-menu-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](https://floating-ui.com/docs/virtual-elements/). |
| `strategy` | string | `'absolute'` | Positioning strategy for the dropdown menu. Use `'absolute'` for default positioning, or `'fixed'` to escape containers with `overflow: hidden`. For more information refer to Floating UI's [strategy docs](https://floating-ui.com/docs/computePosition#strategy). |
#### Using function with `floatingConfig`
```js
const dropdown = new coreui.Dropdown(element, {
floatingConfig(defaultConfig) {
// const newConfig = {...}
// use defaultConfig if needed...
// return newConfig
}
})
```
### 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: `coreui.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: `coreui.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 `.dropdown-menu`'s parent element and have a `relatedTarget` property, whose value is the toggling anchor element.
`hide.coreui.dropdown` and `hidden.coreui.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 |
| --- | --- |
| `hidden.coreui.dropdown` | Fired when the dropdown has finished being hidden from the user and CSS transitions have completed. |
| `hide.coreui.dropdown` | Fires immediately when the `hide` instance method has been called. |
| `show.coreui.dropdown` | Fires immediately when the `show` instance method is called. |
| `shown.coreui.dropdown` | Fired when the dropdown has been made visible to the user and CSS transitions have completed. |
```js
const myDropdown = document.getElementById('myDropdown')
myDropdown.addEventListener('show.coreui.dropdown', event => {
// do something...
})
```
## Customizing
### CSS variables
Dropdowns use local CSS variables on `.dropdown-menu` for enhanced real-time customization.
```scss
$dropdown-tokens: defaults(
(
--cui-dropdown-zindex: var(--cui-z-dropdown),
--cui-dropdown-min-width: 10rem,
--cui-dropdown-padding-x: 0,
--cui-dropdown-padding-y: .5rem,
--cui-dropdown-spacer: .125rem,
--cui-dropdown-font-size: var(--cui-body-font-size),
--cui-dropdown-color: var(--cui-fg-body),
--cui-dropdown-bg: var(--cui-bg-body),
--cui-dropdown-border-color: #{$dropdown-border-color},
--cui-dropdown-border-radius: var(--cui-radius-7),
--cui-dropdown-border-width: var(--cui-border-width),
--cui-dropdown-divider-bg: #{$dropdown-border-color},
--cui-dropdown-divider-margin-y: var(--cui-spacer-3),
--cui-dropdown-box-shadow: var(--cui-box-shadow),
--cui-dropdown-link-color: var(--cui-fg-body),
--cui-dropdown-link-hover-color: var(--cui-fg-body),
--cui-dropdown-link-hover-bg: var(--cui-bg-1),
--cui-dropdown-link-active-color: var(--cui-primary-contrast),
--cui-dropdown-link-active-bg: var(--cui-primary-base),
--cui-dropdown-link-disabled-color: var(--cui-fg-3),
--cui-dropdown-item-padding-x: var(--cui-spacer),
--cui-dropdown-item-border-radius: 0,
--cui-dropdown-item-padding-y: var(--cui-spacer-1),
--cui-dropdown-header-color: var(--cui-fg-3),
--cui-dropdown-header-padding-x: var(--cui-spacer),
--cui-dropdown-header-padding-y: .5rem,
),
$dropdown-tokens
);
```
The caret that indicates a dropdown's interactivity sizes itself from one token on `.dropdown-toggle`; the gap before it and its vertical alignment are computed from that width, so retuning it moves all three.
```scss
$caret-tokens: defaults(
(
--cui-caret-width: .3em,
--cui-caret-spacing: calc(var(--cui-caret-width) * .85),
--cui-caret-vertical-align: calc(var(--cui-caret-width) * .85),
),
$caret-tokens
);
```
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-dark-tokens: defaults(
(
--cui-dropdown-color: var(--cui-gray-300),
--cui-dropdown-bg: var(--cui-gray-800),
--cui-dropdown-border-color: #{$dropdown-border-color},
--cui-dropdown-link-color: var(--cui-gray-300),
--cui-dropdown-link-hover-color: var(--cui-white),
--cui-dropdown-divider-bg: #{$dropdown-border-color},
--cui-dropdown-link-hover-bg: color-mix(in oklch, var(--cui-white) 15%, transparent),
--cui-dropdown-link-active-color: var(--cui-primary-contrast),
--cui-dropdown-link-active-bg: var(--cui-primary-base),
--cui-dropdown-link-disabled-color: var(--cui-gray-500),
--cui-dropdown-header-color: var(--cui-gray-500),
),
$dropdown-dark-tokens
);
```
### Sass variables
_Deprecated in 6.0.0._
Sass variables set these defaults at build time and are removed in v7. The CSS variables above reach the same values without recompiling, and can be set on a single element.
Variables for all dropdowns:
```scss
$dropdown-border-color: var(--cui-border-color-translucent) !default;
```
### 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: var(--cui-caret-width, .3em)) {
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: var(--cui-caret-width, .3em)) {
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: var(--cui-caret-width, .3em)) {
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: var(--cui-caret-width, .3em)) {
border-block-start: $width solid transparent;
border-block-end: $width solid transparent;
border-inline-end: $width solid;
}
@mixin caret(
$direction: down,
$width: var(--cui-caret-width, .3em),
$spacing: var(--cui-caret-spacing, calc(var(--cui-caret-width, .3em) * .85)),
$vertical-align: var(--cui-caret-vertical-align, calc(var(--cui-caret-width, .3em) * .85))
) {
@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;
}
}
}
```