BootstrapVueNext

Dropdowns are toggleable, contextual overlays for displaying lists of links and actions in a dropdown menu format.

BDropdown components are toggleable, contextual overlays for displaying lists of links, and more. They're toggled by clicking (or pressing space or enter when focused), not by hovering; this is an intentional design decision.

HTML

template

<BDropdown text="Dropdown Button" class="me-2">
  <BDropdownItem>First Action</BDropdownItem>
  <BDropdownItem>Second Action</BDropdownItem>
  <BDropdownItem>Third Action</BDropdownItem>
  <BDropdownDivider />
  <BDropdownItem active>Active action</BDropdownItem>
  <BDropdownItem disabled>Disabled action</BDropdownItem>
</BDropdown>

Button content

You can customize the text of the dropdown button by using either the text prop (shown in previous examples), or use the button-content slot instead of the text prop. The button-content slot allows you to use basic HTML and icons in the button content.

If both the prop text and slot button-content are present, the slot button-content will take precedence.

HTML

template

<div class="d-flex gap-2">
  <BDropdown text="Button text via Prop" class="me-2">
    <BDropdownItem href="#">An item</BDropdownItem>
    <BDropdownItem href="#">Another item</BDropdownItem>
  </BDropdown>
  <BDropdown class="me-2">
    <template #button-content>
      Custom <strong>Content</strong> with <em>HTML</em> via Slot
    </template>
    <BDropdownItem href="#">An item</BDropdownItem>
    <BDropdownItem href="#">Another item</BDropdownItem>
  </BDropdown>
</div>

Positioning

Dropdown supports various positioning such as left (start) and right (end) aligned, dropdown and dropup, and supports auto-flipping dropdown to dropup, and vice-versa) when the menu would overflow off of the visible screen area.

The dropdown menu can either be start aligned (default) or end aligned to the button above it. To have the dropdown aligned on the end, set the end prop.

HTML

template

<BDropdown text="Default Alignment" variant="primary" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>
<BDropdown start text="Start Alignment" variant="primary" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>
<BDropdown end text="End Align" variant="primary" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>
<BDropdown center text="Center" variant="primary" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>

Dropup

Turn your dropdown menu into a drop-up menu by setting the placement prop.

HTML

template

<BDropdown placement="top" text="Drop-Up" variant="primary" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>

Drop placement

Turn your dropdown menu into a drop left, right or other menu by setting the placement prop.

Values for placement come from floating-ui's placement definition.

HTML

template

<BDropdown placement="right" text="Drop-right" variant="primary" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>
<BDropdown placement="left" text="Drop-left" variant="primary" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>
<BDropdown placement="right-start" text="Drop-right-start" variant="primary" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>
<BDropdown placement="left-end" text="Drop-left-end" variant="primary" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>

Auto "flipping"

By default, dropdowns may flip to the top, or the bottom, based on their current position in the viewport. To disable this auto-flip feature, set the no-flip prop.

HTML

template

<BDropdown text="No flipping" no-flip class="me-2">
  <BDropdownItem href="#">An item</BDropdownItem>
  <BDropdownItem href="#">Another item</BDropdownItem>
  <BDropdownItem href="#">Yet Another item</BDropdownItem>
</BDropdown>

Like to move your menu away from the toggle buttons a bit? Then use the offset prop to specify the number of pixels to push right (or left when negative) from the toggle button:

HTML

template

<BDropdown offset="25" text="Offset Dropdown" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>
<BDropdown
  :offset="{alignmentAxis: 50, crossAxis: 60, mainAxis: 70}"
  text="Offset Dropdown 2 dimensions"
  class="me-2"
>
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>

Floating Strategy

By default, the floating element will render using absolute. You can change this using the strategy prop. The only other option is fixed. See the floating-ui documentation for details.

HTML

template

<BDropdown text="Strategy fixed" strategy="fixed" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>

Boundary constraint

By default, dropdowns are visually constrained to their clipping ancestors, which will suffice in most situations. However, if you place a dropdown inside an element that has overflow: scroll (or similar) set, the dropdown menu may - in some situations - get cut off. To get around this, you can specify a boundary element via the boundary prop. Supported values any values from floating-ui Boundary or RootBoundary types. The default value is clippingAncestors.

Note: When boundary is any value other than the default of clippingAncestors, the style position: static is applied to the dropdown component's root element to allow the menu to "break out" of its scroll container. In some situations, this may affect your layout or positioning of the dropdown trigger button. In these cases, you may need to wrap your dropdown inside another element

Note: BootstrapVueNext uses floating-ui under the hood, so please read their options documnetation for details on boundary and boundary-padding.

Container element

By default, dropdowns are next to the toggle button. However, you can specify a container element via the container prop where dropdowns will be teleported to instead. Supported values are CSS selector string, an actual DOM node or a reference to an HTML element.

By default, the dropdown menu is closed when clicking inside or outside the dropdown menu. You can use the auto-close property to change this behavior of the dropdown.

The auto-closeproperty has 4 options.

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 the hide 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

HTML

template

<BDropdown text="Default Dropdown" class="me-2">
  <BDropdownItemButton>Action</BDropdownItemButton>
  <BDropdownItemButton>Another action</BDropdownItemButton>
  <BDropdownItemButton>Something else here</BDropdownItemButton>
</BDropdown>
<BDropdown text="Clickable outside (auto-close=inside)" auto-close="inside" class="me-2">
  <BDropdownItemButton>Action</BDropdownItemButton>
  <BDropdownItemButton>Another action</BDropdownItemButton>
  <BDropdownItemButton>Something else here</BDropdownItemButton>
</BDropdown>
<BDropdown text="Clickable inside (auto-close=outside)" auto-close="outside" class="me-2">
  <BDropdownItemButton>Action</BDropdownItemButton>
  <BDropdownItemButton>Another action</BDropdownItemButton>
  <BDropdownItemButton>Something else here</BDropdownItemButton>
</BDropdown>
<BDropdown text="Manual close (auto-close=false)" :auto-close="false" class="me-2">
  <BDropdownItemButton>Action</BDropdownItemButton>
  <BDropdownItemButton>Another action</BDropdownItemButton>
  <BDropdownItemButton>Something else here</BDropdownItemButton>
</BDropdown>

Advanced floating-ui configuration

Occasionally you may want to modify the floating-ui behavior. We already expose some configurations through the no-flip, no-shift, strategy, and offset props. However, lower-level access to the API may sometimes be required. You can use the floatingMiddleware prop to define middleware to pass through to the floating-ui element.

You can view the Floating-ui docs to learn more about their middleware. Note: You will likely want to install @floating-ui/vue to use their middleware directly, rather than rebuilding middleware options.

Note: Using the floatingMiddleware prop will overwrite other defined middleware such as offset, noFlip, and noShift. They are not merged.

Split button support

Create a split dropdown button, where the left button provides standard click event and link support, while the right-hand side is the dropdown menu toggle button.

HTML

template

<BDropdown split text="Split Dropdown" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here...</BDropdownItem>
</BDropdown>

Split button link support

The left split button defaults to an element of type <button> (a BButton to be exact). To convert this button into a link or RouterLink, specify the href via the split-href prop or a router link to value via the split-to prop, while maintaining the look of a button.

Split Link

HTML

template

<BDropdown split split-href="#foo/bar" text="Split Link" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here...</BDropdownItem>
</BDropdown>

Split button type

The split button defaults to a button type of button. You can specify an alternate type via the split-button-type prop. Supported values are: button, submit, and reset.

If props split-to or split-href are set, the split-button-type prop will be ignored.

Styling options

Dropdowns support various props for styling the dropdown trigger button.

Sizing

Dropdowns work with trigger buttons of all sizes, including default and split dropdown buttons.

Set the size prop to either sm for a small button, or lg for a large button.

HTML

template

<div class="d-flex flex-wrap gap-2">
  <BDropdown size="lg" text="Large" class="me-2">
    <BDropdownItemButton>Action</BDropdownItemButton>
    <BDropdownItemButton>Another action</BDropdownItemButton>
    <BDropdownItemButton>Something else here</BDropdownItemButton>
  </BDropdown>
  <BDropdown size="lg" split text="Large Split" class="me-2">
    <BDropdownItemButton>Action</BDropdownItemButton>
    <BDropdownItemButton>Another action</BDropdownItemButton>
    <BDropdownItemButton>Something else here...</BDropdownItemButton>
  </BDropdown>
</div>
<div class="d-flex flex-wrap gap-2 mt-2">
  <BDropdown size="sm" text="Small" class="me-2">
    <BDropdownItemButton>Action</BDropdownItemButton>
    <BDropdownItemButton>Another action</BDropdownItemButton>
    <BDropdownItemButton>Something else here...</BDropdownItemButton>
  </BDropdown>
  <BDropdown size="sm" split text="Small Split" class="me-2">
    <BDropdownItemButton>Action</BDropdownItemButton>
    <BDropdownItemButton>Another action</BDropdownItemButton>
    <BDropdownItemButton>Something else here...</BDropdownItemButton>
  </BDropdown>
</div>

Note: changing the size of the button(s) does not affect the size of the menu items!

The dropdown toggle button can have one of the standard Bootstrap contextual variants applied by setting the prop variant to success, primary, info, danger, link, outline-dark, etc. (or custom variants, if defined). The default variant is secondary.

See the Variant Reference for a full list of built-in contextual variants.

HTML

template

<BDropdown text="Primary" variant="primary" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>
<BDropdown text="Success" variant="success" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>
<BDropdown text="Outline Danger" variant="outline-danger" class="me-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>

You can also apply arbitrary classes to the toggle button via the toggle-class prop.

Split button color variant

By default, the left split button uses the same variant as the toggle button. You can give the split button its variant via the split-variant prop.

HTML

template

<BDropdown
  split
  split-variant="outline-primary"
  variant="primary"
  text="Split Variant Dropdown"
  class="me-2"
>
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here...</BDropdownItem>
</BDropdown>

Dark mode

Dark variants for components were deprecated in Bootstrap v5.3.0. See their documentation for details.

Block level dropdowns

By default, dropdowns act like buttons and are displayed inline. Create a full-width, “block button” by adding the classes d-grid and gap-2 to the BDropdown. For split buttons, wrap the BDropdown in a div that has the d-grid and gap-2 classes and add split-class="w-100" to the BDropdown itself. See the Bootstrap 5 button documentation for details

HTML

template

<BDropdown text="Block Level Dropdown" variant="primary" class="d-grid gap-2 mb-2">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>
<div class="d-grid gap-2">
  <BDropdown
    text="Block Level Split Dropdown"
    split
    split-variant="outline-primary"
    variant="primary"
    split-class="w-100"
  >
    <BDropdownItem href="#">Action</BDropdownItem>
    <BDropdownItem href="#">Another action</BDropdownItem>
    <BDropdownItem href="#">Something else here...</BDropdownItem>
  </BDropdown>
</div>

If you want the dropdown menu to span to the full width of the parent container too, add the w-100 utility class to the menu-class prop.

HTML

template

<BDropdown text="Block Level Dropdown Menu" block variant="primary" menu-class="w-100">
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here</BDropdownItem>
</BDropdown>

Many of the supported dropdown sub-components provide a variant prop for controlling their text color.

Hidden caret

The dropdown can be created with the toggle's caret visually hidden by setting the no-caret prop to true. This is useful when the dropdown is to be displayed as an icon.

HTML

template

<BDropdown size="lg" variant="link" toggle-class="text-decoration-none" no-caret>
  <template #button-content> &#x1f50d;<span class="visually-hidden">Search</span> </template>
  <BDropdownItem href="#">Action</BDropdownItem>
  <BDropdownItem href="#">Another action</BDropdownItem>
  <BDropdownItem href="#">Something else here...</BDropdownItem>
</BDropdown>

Note: The caret will always be shown when using split mode.

v-model support

The dropdown's opened state is bound to the component's v-model. Programatic control of the state of the dropdown can be managed via the model. The model can also be used to observe the state of the dropdown.

Open: false

HTML

vue

<template>
  <p>Open: {{ model }}</p>

  <div class="d-flex gap-2 mb-2">
    <BButton @click="model = true">Open Dropdown</BButton>
    <BButton @click="model = false">Close Dropdown</BButton>
  </div>

  <BDropdown v-model="model" text="Dropdown Button" class="me-2">
    <BDropdownItem>First Action</BDropdownItem>
    <BDropdownItem>Second Action</BDropdownItem>
    <BDropdownItem>Third Action</BDropdownItem>
    <BDropdownDivider />
    <BDropdownItem active>Active action</BDropdownItem>
    <BDropdownItem disabled>Disabled action</BDropdownItem>
  </BDropdown>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const model = ref<boolean>(false)
</script>

Exposed Methods

You are also able to use the built in methods for showing, hiding or toggling the dropdown viatemplate refs.

show: shows the dropdown
hide: hides the dropdown
toggle: toggles the dropdown

HTML

vue

<template>
  <div class="d-flex gap-2 mb-2">
    <BButton variant="danger" @click="show">Show</BButton>
    <BButton variant="success" @click="hide">Hide</BButton>
    <BButton @click="toggle">Toggle</BButton>
  </div>

  <BDropdown ref="myDropdown" text="Dropdown Button" :auto-close="false" class="me-2">
    <BDropdownItem>First Action</BDropdownItem>
    <BDropdownItem>Second Action</BDropdownItem>
    <BDropdownItem>Third Action</BDropdownItem>
    <BDropdownDivider />
    <BDropdownItem active>Active action</BDropdownItem>
    <BDropdownItem disabled>Disabled action</BDropdownItem>
  </BDropdown>
</template>

<script setup lang="ts">
import type {BDropdown} from 'bootstrap-vue-next'
import {ref} from 'vue'

const myDropdown = ref<null | InstanceType<typeof BDropdown>>(null)

const show = () => myDropdown.value?.show()
const hide = () => myDropdown.value?.hide()
const toggle = () => myDropdown.value?.toggle()
</script>

The following components can be placed inside your dropdowns. Using any other component or markup may break layout and/or keyboard navigation.

Sub-component	Description
`BDropdownItem`	Action items that provide click, link, and `RouterLink`/`NuxtLink` functionality. Renders as an `<a>` element by default
`BDropdownItemButton`	An alternative to `BDropdownItem` that renders a menu item using a `<button>` element
`BDropdownDivider`	A divider/spacer which can be used to separate dropdown items
`BDropdownText`	Free flowing text content in a menu
`BDropdownGroup`	For grouping dropdown sub-components with an optional header
`BDropdownHeader`	A header item, used to help identify a group of dropdown items
`BDropdownForm`	For placing form controls within a dropdown menu.

WARNING

Nested sub-menus are not supported.

TIP

There are small differences in how the sub-components behave, please read our migration guide if you are converting from bootstrap-vue.

BDropdownItem

The BDropdownItem is typically used to create a navigation link inside your menu. Use either the href prop or the to prop (for router link support) to generate the appropriate navigation link. If neither href nor to are provided, a standard <a> link will be generated with an href of # (with an event handler that will prevent scroll to top behavior by preventing the default link action).

Disabled the dropdown item by setting the disabled prop.

HTML

template

<BDropdown text="Dropdown">
  <BDropdownItem>First Action</BDropdownItem>
  <BDropdownItem variant="primary">Second Action</BDropdownItem>
  <BDropdownItem active>Active action</BDropdownItem>
  <BDropdownItem disabled>Disabled action</BDropdownItem>
  <BDropdownItem to="/docs/components/badge">Badge</BDropdownItem>
</BDropdown>

BDropdownItemButton

Historically dropdown menu contents had to be links (BDropdownItem), but that is no longer the case with Bootstrap v5. Now you can optionally create <button> elements in your dropdowns by using the BDropdownItemButton sub-component. BDropdownItemButton does not support the href or to props.

Disabled the dropdown item button by setting the disabled prop.

HTML

template

<BDropdown text="Dropdown using buttons as menu items">
  <BDropdownItemButton>I am a button</BDropdownItemButton>
  <BDropdownItemButton active>I am a active button</BDropdownItemButton>
  <BDropdownItemButton disabled>I am a button, but disabled!</BDropdownItemButton>
  <BDropdownItemButton>I do not look like a button, but I am!</BDropdownItemButton>
</BDropdown>

When the menu item does not trigger navigation, it is recommended to use the BDropdownItemButton sub-component.

BDropdownDivider

Separate groups of related menu items with BDropdownDivider.

HTML

template

<BDropdown text="Dropdown with divider">
  <BDropdownItemButton>First item</BDropdownItemButton>
  <BDropdownItemButton>Second item</BDropdownItemButton>
  <BDropdownDivider />
  <BDropdownItemButton>Separated Item</BDropdownItemButton>
</BDropdown>

BDropdownText

Place any freeform text within a dropdown menu using the BDropdownText sub-component or use text combined with spacing utilities. Note that you'll likely need additional sizing styles to constrain/set the menu width.

HTML

template

<BDropdown text="Dropdown with text">
  <BDropdownText style="width: 240px">
    Some example text that is free-flowing within the dropdown menu.
  </BDropdownText>
  <BDropdownText tag="span">And this is more example text.</BDropdownText>
  <BDropdownDivider />
  <BDropdownItemButton>First item</BDropdownItemButton>
  <BDropdownItemButton>Second Item</BDropdownItemButton>
</BDropdown>

BDropdownText has the BootstrapVueNext custom class .b-dropdown-text applied to it which sets some basic styles which are suitable in most situations. By default, its width will be the same as the widest BDropdownItem content. You may need to place additional styles or helper classes on the component.

variant)

BDropdownGroup

Group a set of dropdown sub-components with an optional associated header. Place a BDropdownDivider between your BDropdownGroup and other groups or non-grouped dropdown contents.

HTML

template

<BDropdown text="Dropdown with group">
  <BDropdownItemButton> Non-grouped Item </BDropdownItemButton>
  <BDropdownDivider />
  <BDropdownGroup header="Group 1">
    <BDropdownItemButton>First Grouped item</BDropdownItemButton>
    <BDropdownItemButton>Second Grouped Item</BDropdownItemButton>
  </BDropdownGroup>
  <BDropdownGroup header="Group 2" header-variant="primary">
    <BDropdownItemButton>First Grouped item</BDropdownItemButton>
    <BDropdownItemButton>Second Grouped Item</BDropdownItemButton>
  </BDropdownGroup>
  <BDropdownDivider />
  <BDropdownItemButton> Another Non-grouped Item </BDropdownItemButton>
</BDropdown>

BDropdownHeader

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

HTML

template

<BDropdown text="Dropdown with header">
  <BDropdownHeader> Dropdown header </BDropdownHeader>
  <BDropdownItemButton aria-describedby="dropdown-header-label"> First item </BDropdownItemButton>
  <BDropdownItemButton aria-describedby="dropdown-header-label">
    Second Item
  </BDropdownItemButton>
</BDropdown>

See Section Headers and accessibility for details on making headers more accessible for users of assistive technologies.

Using the BDropdownGroup sub-component simplifies creating accessible grouped dropdown items with an associated header.

BDropdownForm

Add a form into your dropdown with BDropdownForm.

HTML

template

<BDropdown text="Dropdown with form" auto-close="outside">
  <BDropdownForm>
    <BFormGroup
      label="Email address:"
      label-for="email"
      description="We'll never share your email with anyone else."
    >
      <BFormInput id="email" type="email" placeholder="Enter email" required />
    </BFormGroup>
    <BFormGroup
      label="Password:"
      label-for="password"
      description="We'll never share your email with anyone else."
    >
      <BFormInput id="password" type="password" required />
    </BFormGroup>
    <BFormCheckbox id="remember" name="remember" value="remember" checked>
      Remember me</BFormCheckbox
    >
    <BButton type="submit" variant="primary">Sign In</BButton>
  </BDropdownForm>
  <BDropdownDivider />
  <BDropdownItemButton>New around here? Sign up</BDropdownItemButton>
  <BDropdownItemButton>Forget Password</BDropdownItemButton>
</BDropdown>

Or make it inline.

HTML

template

<BDropdown text="Dropdown with inline form" auto-close="outside">
  <BDropdownForm form-class="d-flex flex-row align-items-center flex-wrap">
    <BFormGroup label="Email:" label-for="email-inline" label-cols="3" label-align="end">
      <BFormInput id="email-inline" type="email" placeholder="Enter email" required />
    </BFormGroup>
    <BFormGroup label="Password:" label-for="password-inline" label-cols="4" label-align="end">
      <BFormInput id="password-inline" type="password" required />
    </BFormGroup>
  </BDropdownForm>
  <BDropdownDivider />
  <BDropdownItemButton>New around here? Sign up</BDropdownItemButton>
  <BDropdownItemButton>Forget Password</BDropdownItemButton>
</BDropdown>

Accessibility

Providing a unique id prop ensures ARIA compliance by automatically adding the appropriate aria-* attributes in the rendered markup. By default, the dropdown will render a unique id for every dropdown. However, this can be overwritten with the prop id.

The default ARIA role is set to menu, but you can change this default to another role (such as navigation) via the role prop, depending on your use case.

When a menu item does not trigger navigation, it is recommended to use the BDropdownItemButton sub-component (which is not announced as a link) instead of BDropdownItem (which is presented as a link to the user).

Headers and accessibility

When using BDropdownHeader components in the dropdown menu, it is recommended to add an id attribute to each of the headers, and then set the aria-describedby attribute (set to the id value of the associated header) on each following dropdown items under that header. This will provide users of assistive technologies (i.e. sight-impaired users) additional context about the dropdown item:

HTML

template

<BDropdown text="Dropdown ARIA" variant="primary">
  <BDropdownHeader id="dropdown-header-1">Groups</BDropdownHeader>
  <BDropdownItemButton aria-describedby="dropdown-header-1">Add</BDropdownItemButton>
  <BDropdownItemButton aria-describedby="dropdown-header-1">Delete</BDropdownItemButton>
  <BDropdownHeader id="dropdown-header-2">Users</BDropdownHeader>
  <BDropdownItemButton aria-describedby="dropdown-header-2">Add</BDropdownItemButton>
  <BDropdownItemButton aria-describedby="dropdown-header-2">Delete</BDropdownItemButton>
  <BDropdownDivider />
  <BDropdownItemButton>
    Something <strong>not</strong> associated with Users
  </BDropdownItemButton>
</BDropdown>

As a simplified alternative, use the BDropdownGroup instead to easily associate header text to the contained dropdown sub-components.

Dropdowns support keyboard navigation, emulating native <select> behavior.

Note that Down and Up will not move focus into BDropdownForm sub-components, but users can still use Tab or Shift+Tab to move into form controls within the menu.

Lazy

Dropdown menus can have their inner content rendered lazily through the lazy prop. By default, this is turned off. For navigation elements, it may be beneficial to keep lazy off, so web crawlers can properly comb through your sites navigation.

HTML

template

<BDropdown lazy text="Dropdown">
  <BDropdownItem>First Action</BDropdownItem>
  <BDropdownItem>Second Action</BDropdownItem>
  <BDropdownItem>Third Action</BDropdownItem>
  <BDropdownDivider />
  <BDropdownItem active>Active action</BDropdownItem>
  <BDropdownItem disabled>Disabled action</BDropdownItem>
</BDropdown>

Implementation notes

The dropdown menu is rendered with semantic <ul> and <li> elements for accessibility reasons. The .dropdown-menu is the <ul> element, while dropdown items (items, buttons, text, form, headers, and dividers) are wrapped in an <li> element. If creating custom items to place inside the dropdown menu, ensure they are wrapped with a plain <li>.

Component Reference

<BDropdown>

View Source

<BDropdown> Properties
<BDropdown> Events
<BDropdown> Slots

Adding styles: .dropdown

Properties

Prop	Type	Default	Description
aria-label	`string`	`undefined`	Sets the value of `aria-label` attribute on the rendered element
auto-close	`boolean \| 'inside' \| 'outside'`	`true`	Controls the automatic closing of the dropdown when clicking. See above for details.
boundary	`Boundary \| RootBoundary`	`'clippingAncestors'`	The boundary constraint of dropdown: any value of floating-us's Boundary or RootBoundary type. See above for details.
boundary-padding	`Padding`	`undefined`	The virtual padding around the boundary to check for overflow
disabled	`boolean`	`false`	When set to `true`, disables the component's functionality and places it in a disabled state
floating-middleware	`Middleware[]`	`undefined`	Directly set the floating-ui middleware behavior. See above for details.
id	`string`	`undefined`	Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
initial-animation	`boolean`	`false`	When set, enables the initial animation on mount
is-nav	`boolean`	`false`	Indicates the dropdown is a nav dropdown
lazy	`boolean`	`false`	When set, the content will not be mounted until opened
menu-class	`ClassValue`	`undefined`	CSS class (or classes) to add to the menu container
model-value	`boolean`	`false`	Controls the visibility of the component
no-animation	`boolean`	`false`	When set, disables the animation
no-caret	`boolean`	`false`	Hide the caret indicator on the toggle button
no-fade	`boolean`	`false`	Alias for `noAnimation`
no-flip	`boolean`	`false`	Prevent the menu from auto flipping positions
no-shift	`boolean`	`false`	Prevent the menu from automatically shifting positions
no-size	`boolean`	`false`	Prevent the menu from automatically resizing
no-wrapper	`boolean`	`false`	Do not render the dropdown wrapper element
offset	`number \| string \| {mainAxis?: number; crossAxis?: number; alignmentAxis?: number \| null`	`0`	Specify the number of pixels to shift the menu by. See above for details.
placement	`Placement`	`'bottom-start'`	Placement of a floating element
role	`string`	`'menu'`	Sets the ARIA attribute `role` to a specific value
show	`boolean`	`false`	When set, and prop 'visible' is false on mount, will animate from closed to open on initial mount. Mainly to help with template show. Use model-value for reactive show/hide
size	`Size`	`'md'`	Set the size of the component's appearance. 'sm', 'md' (default), or 'lg'
split	`boolean`	`false`	When set, renders a split button dropdown
split-button-type	`ButtonType`	`'button'`	Value to place in the 'type' attribute on the split button: 'button', 'submit', 'reset'
split-class	`ClassValue`	`undefined`	CSS class (or classes) to add to the split button
split-disabled	`boolean`	`undefined`	When set, the split button is disabled
split-href	`string`	`undefined`	Denotes the target URL of the link for the split button
split-to	`RouteLocationRaw`	`undefined`	Denotes the target route of the split button. When clicked, the value of the to prop will be passed to router.push() internally, so the value can be either a string or a Location descriptor object
split-variant	`ButtonVariant \| null`	`undefined`	Applies one of the Bootstrap theme color variants to the split button. Defaults to the 'variant' prop value
strategy	`Strategy`	`'absolute'`	The strategy used to determine when to hide the dropdown. See above for details.
teleport-disabled	`boolean`	`false`	Renders the dropdown in the exact place it was defined
teleport-to	`string \| RendererElement \| null \| undefined`	`undefined`	Overrides the default teleport location
text	`string`	`undefined`	Text to place in the toggle button, or in the split button is split mode
toggle-class	`ClassValue`	`undefined`	CSS class (or classes) to add to the toggle button
toggle-text	`string`	`'Toggle dropdown'`	ARIA label (visually-hidden) to set on the toggle when in split mode. Overriden by the slot of the same name
trans-props	`TransitionProps`	`undefined`	Transition properties
unmount-lazy	`boolean`	`false`	When set and `lazy` is true, the content will be unmounted when closed
variant	`ColorVariant \| null`	`'secondary'`	Applies one of the Bootstrap theme color variants to the component. When implemented `bg-variant` and `text-variant` will take precedence
visible	`boolean`	`false`	When 'true', open without animation
wrapper-class	`ClassValue`	`undefined`	CSS class (or classes) to add to the wrapper element

Events

Event	Args	Description
click	`event: MouseEvent` - Native click event object	Emitted when button is clicked
hidden		Called after dropdown is hidden
hide	`value: BvTriggerableEvent` - Call value.preventDefault() to cancel hide	Emitted just before dropdown is hidden. Cancelable
hide-prevented		Emitted when the dropdown tried to close, but was prevented from doing so.
show	`value: BvTriggerableEvent` - Call value.preventDefault() to cancel show	Emitted just before dropdown is shown. Cancelable
show-prevented		Emitted when the dropdown tried to open, but was prevented from doing so.
shown		Called after dropdown is shown
split-click	`event: MouseEvent` - Native click event object	Emitted when split button is clicked in split mode
toggle		Emitted when toggle button is clicked

Slots

Name	Scope	Description
button-content		Can be used to implement custom text with icons and more styling
default	`hide: () => void` - Can be used to close the dropdown `show: () => void` - Can be used to open the dropdown	Optionally scoped default slot for dropdown menu content
toggle-text		ARIA label (visually-hidden) to set on the toggle when in split mode. Overrides the toggle-text prop

<BDropdownDivider>

View Source

<BDropdownDivider> Properties

Adding styles: .dropdown‑divider

Properties

Prop	Type	Default	Description
divider-class	`ClassValue`	`undefined`	CSS class (or classes) to add to the divider component
tag	`string`	`'hr'`	Specify the HTML tag to render instead of the default tag
variant	`ColorVariant \| null`	`null`	Applies one of the Bootstrap theme color variants to the component. When implemented `bg-variant` and `text-variant` will take precedence
wrapper-attrs	`Readonly<AttrsValue>`	`undefined`	Attributes to be applied to the wrapper element

<BDropdownForm>

View Source

<BDropdownForm> Properties
<BDropdownForm> Slots

Adding styles: .dropdown‑form

Properties

Prop	Type	Default	Description
form-class	`ClassValue`	`undefined`	CSS class (or classes) to add to the form component
novalidate		`undefined`	Not yet implemented
validated		`undefined`	Not yet implemented
wrapper-attrs	`Readonly<AttrsValue>`	`undefined`	Attributes to be applied to the wrapper element

Slots

Name	Scope	Description
default		Content to place in the dropdown form

<BDropdownGroup>

View Source

<BDropdownGroup> Properties
<BDropdownGroup> Slots

Adding styles: .dropdown‑group

Properties

Prop	Type	Default	Description
aria-describedby	`string`	`undefined`	The ID of the element that provides a description for this component. Used as the value for the `aria-describedby` attribute
header	`string`	`undefined`
header-class	`ClassValue`	`undefined`	CSS class (or classes) to apply to the header
header-tag	`string`	`'header'`	Specify the HTML tag to render instead of the default tag for the header
header-variant	`ColorVariant \| null`	`undefined`	Applies one of the Bootstrap theme color variants to the header
id	`string`	`undefined`	Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed

Slots

Name	Scope	Description
default		Content (items) to place in the dropdown group
header		Optional header content for the dropdown group

<BDropdownHeader>

View Source

<BDropdownHeader> Properties
<BDropdownHeader> Slots

Adding styles: .dropdown‑header

Properties

Prop	Type	Default	Description
header-class	`ClassValue`	`undefined`	CSS class (or classes) to apply to the header
tag	`string`	`'div'`	Specify the HTML tag to render instead of the default tag
text	`string`	`undefined`	Content to place in the dropdown text. Default slot takes precedence
variant	`ColorVariant \| null`	`null`	Applies one of the Bootstrap theme color variants to the component. When implemented `bg-variant` and `text-variant` will take precedence
wrapper-attrs	`Readonly<AttrsValue>`	`undefined`	Attributes to be applied to the wrapper element

Slots

Name	Scope	Description
default		Content to place in the dropdown header

<BDropdownItem>

View Source

<BDropdownItem> Properties
<BDropdownItem> Events
<BDropdownItem> Slots

Adding styles: .dropdown‑item

Properties

Prop	Type	Default	Description
link-class	`ClassValue`	`undefined`	Class or classes to apply to the inner link element
wrapper-attrs	`Readonly<AttrsValue>`	`undefined`	Attributes to be applied to the wrapper element

Extensions:

BLink props

Prop	Type	Default	Description
active	`boolean`	`undefined`	When set to `true`, places the component in the active state with active styling
active-class	`string`	`'router-link-active'`	Configure the active CSS class applied when the link is active.
disabled	`boolean`	`false`	When set to `true`, disables the link's functionality. See above for details and limitations
exact-active-class	`string`	`'router-link-exact-active'`	Configure the active CSS class applied when the link is active with exact match.
href	`string`	`undefined`	Denotes the target URL of the link for standard a links
icon	`boolean`	`false`	When set to `true`, styles an icon at the beginning or end of the link text
no-prefetch	`boolean`	`false`	To improve the responsiveness of your Nuxt.js applications, when the link will be displayed within the viewport, Nuxt.js will automatically prefetch the code splitted page. Setting `no-prefetch` will disabled this feature for the specific link
no-rel		`undefined`
opacity	`10 \| 25 \| 50 \| 75 \| 100 \| '10' \| '25' \| '50' \| '75' \| '100'`	`undefined`	Change the alpha opacity of the link `rgba()` color value
opacity-hover	`10 \| 25 \| 50 \| 75 \| 100 \| '10' \| '25' \| '50' \| '75' \| '100'`	`undefined`	Change the alpha opacity of the link `rgba()` color value on hover
prefetch	`boolean`	`undefined`	To improve the responsiveness of your Nuxt.js applications, when the link will be displayed within the viewport, Nuxt.js will automatically prefetch the code splitted page. Setting `prefetch` to `true` or `false` will overwrite the default value of `router.prefetchLinks`
prefetch-on	`Partial<{visibility: boolean, interaction: boolean}>`	`undefined`	Allows custom control of when to prefetch links. Possible options are 'interaction' and 'visibility' (default).
prefetched-class	`string`	`undefined`	Not Yet Implmented: A class to apply to links that have been prefetched.
rel	`string`	`undefined`	Sets the 'rel' attribute on the rendered link
replace	`boolean`	`false`	Setting replace prop will call router.replace() instead of router.push() when clicked
router-component-name	`string`	`'router-link'`	BootstrapVue auto detects between `<router-link>` and `<nuxt-link>`. Set this this property to explicity set the name of the router component.
stretched	`boolean`	`false`	When set to `true`, makes the link's `containing block` clickable via an `::after` pseudo element
target	`LinkTarget`	`undefined`	Sets the 'target' attribute on the rendered link
to	`RouteLocationRaw`	`undefined`	Denotes the target route of the link. When clicked, the value of the to prop will be passed to `router.push()` internally
underline-offset	`1 \| 2 \| 3 \| '1' \| '2' \| '3'`	`undefined`	Change the distance of the underline from the bottom of the link text
underline-offset-hover	`1 \| 2 \| 3 \| '1' \| '2' \| '3'`	`undefined`	Change the distance of the underline from the bottom of the link text on hover
underline-opacity	`0 \| 10 \| 25 \| 50 \| 75 \| 100 \| '0' \| '10' \| '25' \| '50' \| '75' \| '100'`	`undefined`	Set's the opacity of the link's underline
underline-opacity-hover	`0 \| 10 \| 25 \| 50 \| 75 \| 100 \| '0' \| '10' \| '25' \| '50' \| '75' \| '100'`	`undefined`	Set's the opacity of the link's underline on hover
underline-variant	`ColorVariant \| null`	`null`	Set the color variant for the link underline independently of the link text
variant	`ColorVariant \| null`	`null`	Set the color variant for the link

Events

Event	Args	Description
click	`value: MouseEvent` - Native click event object	Emitted when item is clicked

Slots

Name	Scope	Description
default		Content to place in the dropdown item

<BDropdownItemButton>

View Source

<BDropdownItemButton> Properties
<BDropdownItemButton> Events
<BDropdownItemButton> Slots

Adding styles: .dropdown‑item‑button

Properties

Prop	Type	Default	Description
active	`boolean`	`false`	When set to `true`, places the component in the active state with active styling
active-class	`ClassValue`	`'active'`	Configure the active CSS class applied when the link is active. Typically you will want to set this to class name 'active'
button-class	`ClassValue`	`undefined`	Class or classes to apply to the inner button element
disabled	`boolean`	`false`	When set to `true`, disables the component's functionality and places it in a disabled state
variant	`ColorVariant \| null`	`null`	Applies one of the Bootstrap theme color variants to the component. When implemented `bg-variant` and `text-variant` will take precedence
wrapper-attrs	`Readonly<AttrsValue>`	`undefined`	Attributes to be applied to the wrapper element

Events

Event	Args	Description
click	`value: MouseEvent` - Native click event object	Emitted when item is clicked

Slots

Name	Scope	Description
default		Content to place in the dropdown item button

<BDropdownText>

View Source

<BDropdownText> Properties
<BDropdownText> Slots

Adding styles: .dropdown‑text

Properties

Prop	Type	Default	Description
tag	`string`	`'span'`	Specify the HTML tag to render instead of the default tag
text	`string`	`undefined`	Content to place in the dropdown text. Default slot takes precedence
text-class	`ClassValue`	`undefined`	CSS class (or classes) to add to the text component
variant	`ColorVariant \| null`	`null`	Applies one of the Bootstrap theme color variants to the component. When implemented `bg-variant` and `text-variant` will take precedence
wrapper-attrs	`Readonly<AttrsValue>`	`undefined`	Attributes to be applied to the wrapper element

Slots

Name	Scope	Description
default		Content to place in the dropdown text

Dropdown ​

Button content ​

Positioning ​

Menu alignment ​

Dropup ​

Drop placement ​

Auto "flipping" ​

Menu offset ​

Floating Strategy ​

Boundary constraint ​

Container element ​

Dropdown auto close behavior ​

Advanced floating-ui configuration ​

Split button support ​

Split button link support ​

Split button type ​

Styling options ​

Sizing ​

Dropdown color variants ​

Split button color variant ​

Dark mode ​

Block level dropdowns ​

Dropdown sub-component color variants ​

Hidden caret ​

v-model support ​

Exposed Methods ​

Dropdown supported sub-components ​

BDropdownItem ​

BDropdownItemButton ​

BDropdownDivider ​

BDropdownText ​

BDropdownGroup ​

BDropdownHeader ​

A nice description

BDropdownForm ​

Accessibility ​

Headers and accessibility ​

Groups

Users

Keyboard navigation ​

Lazy ​

Implementation notes ​

See also ​

Component Reference

Dropdown

Button content

Positioning

Menu alignment

Dropup

Drop placement

Auto "flipping"

Menu offset

Floating Strategy

Boundary constraint

Container element

Dropdown auto close behavior

Advanced floating-ui configuration

Split button support

Split button link support

Split button type

Styling options

Sizing

Dropdown color variants

Split button color variant

Dark mode

Block level dropdowns

Dropdown sub-component color variants

Hidden caret

v-model support

Exposed Methods

Dropdown supported sub-components

BDropdownItem

BDropdownItemButton

BDropdownDivider

BDropdownText

BDropdownGroup

BDropdownHeader

BDropdownForm

Accessibility

Headers and accessibility

Keyboard navigation

Lazy

Implementation notes

See also