Dropdowns

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

<b-dropdown> (or known by its shorter alias of <b-dd>) 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.

<div>
  <b-dropdown id="ddown1" text="Dropdown Button" class="m-md-2">
    <b-dropdown-item>First Action</b-dropdown-item>
    <b-dropdown-item>Second Action</b-dropdown-item>
    <b-dropdown-item>Third Action</b-dropdown-item>
    <b-dropdown-divider />
    <b-dropdown-item active>Active action</b-dropdown-item>
    <b-dropdown-item disabled>Disabled action</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown.vue -->

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.

<div>
  <b-dropdown text="Button text via Prop">
    <b-dropdown-item href="#">An item</b-dropdown-item>
    <b-dropdown-item href="#">Another item</b-dropdown-item>
  </b-dropdown>

  <b-dropdown>
    <template slot="button-content">
      Custom <strong>Content</strong> with <em>HTML</em> via Slot
    </template>
    <b-dropdown-item href="#">An item</b-dropdown-item>
    <b-dropdown-item href="#">Another item</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown-button-content.vue -->

Positioning

Dropdown supports various positioning such as left and right 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 left aligned (default) or right aligned with respect to the button above it. To have the dropdown aligned on the right, set the right prop.

<div>
  <b-dropdown id="ddown-left" text="Left align" variant="primary" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here</b-dropdown-item>
  </b-dropdown>

  <b-dropdown id="ddown-right" right text="Right align" variant="primary" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown-right.vue -->

Dropup

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

<div>
  <b-dropdown id="ddown-dropup" dropup text="Drop-Up" variant="primary" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown-dropup.vue -->

Drop right or left

Turn your dropdown menu into a drop-right menu by setting the dropright prop. Or, turn it into a drop-left menu by setting the dropleft right prop to true.

dropright takes precedence over dropleft. Neither dropright or dropleft have any effect if dropup is set.

<div>
  <b-dropdown id="ddown-dropright" dropright text="Drop-Right" variant="primary" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here</b-dropdown-item>
  </b-dropdown>

  <b-dropdown id="ddown-dropleft" dropleft text="Drop-Left" variant="primary" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown-droprightleft.vue -->

Auto "flipping"

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

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:

  • Specified as a number of pixels: positive for right shift, negative for left shift.
  • Specify the distance in CSS units (i.e. 0.3rem, 4px, 1.2em, etc) passed as a string.
<div>
  <b-dropdown id="ddown-offset" offset="25" text="Offset Dropdown" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown-offset.vue -->

Boundary constraint

By default, dropdowns are visually constrained to its scroll parent, 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 are 'scrollParent' (the default), 'viewport', 'window' or a reference to an HTML element. The boundary value is passed directly to Popper.js's boundariesElement configuration option.

Note: when boundary is any value other than the default of 'scrollParent', the style position: static is applied to to the dropdown component's root element in order 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.

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.

<div>
  <b-dropdown text="Primary" variant="primary" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here</b-dropdown-item>
  </b-dropdown>

  <b-dropdown text="Success" variant="success" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here</b-dropdown-item>
  </b-dropdown>

  <b-dropdown text="Outline Danger" variant="outline-danger" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown-variants.vue -->

You can also apply arbitrary classes to the toggle button via the toggle-class prop. This prop accepts either a string or array of strings.

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.

<div>
  <b-dropdown split text="Split Dropdown" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here...</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown-split.vue -->

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 own variant via the split-variant prop.

<div>
  <b-dropdown
    split
    split-variant="outline-primary"
    variant="primary"
    text="Split Variant Dropdown"
    class="m-2"
  >
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here...</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown-split-variant.vue -->

The left split button defaults to an element of type <button> (a <b-button> to be exact). To convert this button into a link or <router-link>, 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.

<div>
  <b-dropdown split split-href="#foo/bar" text="Split Link" class="m-2">
    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here...</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown-split-link.vue -->

Sizing

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

Set the size prop to either sm for small button(s), or lg for large button(s).

<div>
  <div>
    <b-dropdown size="lg" text="Large" class="m-2">
      <b-dropdown-item-button>Action</b-dropdown-item-button>
      <b-dropdown-item-button>Another action</b-dropdown-item-button>
      <b-dropdown-item-button>Something else here</b-dropdown-item-button>
    </b-dropdown>

    <b-dropdown size="lg" split text="Large Split" class="m-2">
      <b-dropdown-item-button>Action</b-dropdown-item-button>
      <b-dropdown-item-button>Another action</b-dropdown-item-button>
      <b-dropdown-item-button>Something else here...</b-dropdown-item-button>
    </b-dropdown>
  </div>
  <div>
    <b-dropdown size="sm" text="Small" class="m-2">
      <b-dropdown-item-button>Action</b-dropdown-item-button>
      <b-dropdown-item-button>Another action</b-dropdown-item-button>
      <b-dropdown-item-button>Something else here...</b-dropdown-item-button>
    </b-dropdown>

    <b-dropdown size="sm" split text="Small Split" class="m-2">
      <b-dropdown-item-button>Action</b-dropdown-item-button>
      <b-dropdown-item-button>Another action</b-dropdown-item-button>
      <b-dropdown-item-button>Something else here...</b-dropdown-item-button>
    </b-dropdown>
  </div>
</div>

<!-- b-dropdown-sizes.vue -->

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

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.

<div>
  <b-dropdown variant="link" size="lg" no-caret>
    <template slot="button-content">&#x1f50d;<span class="sr-only">Search</span></template>

    <b-dropdown-item href="#">Action</b-dropdown-item>
    <b-dropdown-item href="#">Another action</b-dropdown-item>
    <b-dropdown-item href="#">Something else here...</b-dropdown-item>
  </b-dropdown>
</div>

<!-- b-dropdown-hidden-caret.vue -->

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

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

Sub-component Description Aliases
<b-dropdown-item> Action items that provide click, link, and <router-link>/<nuxt-link> functionality. Renders as an <a> element by default. <b-dd-item>
<b-dropdown-item-button> An alternative to <b-dropdown-item> that renders a menu item using a <button> element. <b-dropdown-item-btn>, <b-dd-item-button>, <b-dd-item-btn>
<b-dropdown-header> A header item, used to help identify a group of dropdown items. <b-dd-header>
<b-dropdown-divider> A divider / spacer which can be used to separate dropdown items. <b-dd-divider>
<b-dropdown-text> Free flowing text content in a menu. <b-dd-text>
<b-dropdown-form> For placing form controls within a dropdown menu. <b-dd-form>

Note: Nested sub-menus are not supported.

<b-dropdown-item>

The <b-dropdown-item> 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 behaviour by preventing the default link action).

Disabled the dropdown item by setting the disabled prop.

<b-dropdown-item-button>

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

Disabled the dropdown item button by setting the disabled prop.

<div>
  <b-dropdown id="ddown-buttons" text="Dropdown using buttons as menu items" class="m-2">
    <b-dropdown-item-button>I'm a button</b-dropdown-item-button>
    <b-dropdown-item-button active>I'm a active button</b-dropdown-item-button>
    <b-dropdown-item-button disabled>I'm a button, but disabled!</b-dropdown-item-button>
    <b-dropdown-item-button>I don't look like a button, but I am!</b-dropdown-item-button>
  </b-dropdown>
</div>

<!-- b-dropdown-item-buttons.vue -->

When the menu item doesn't trigger navigation, it is recommended to use the <b-dropdown-item-button> sub-component.

<b-dropdown-item-divider>

Separate groups of related menu items with <b-dropdown-divider>.

<div>
  <b-dropdown id="ddown-divider" text="Dropdown with divider" class="m-2">
    <b-dropdown-item-button>First item</b-dropdown-item-button>
    <b-dropdown-item-button>Second item</b-dropdown-item-button>
    <b-dropdown-divider />
    <b-dropdown-item-button>Separated Item</b-dropdown-item-button>
  </b-dropdown>
</div>

<!-- b-dropdown-item-divider.vue -->

<b-dropdown-item-header>

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

<div>
  <b-dropdown id="ddown-header" text="Dropdown with header" class="m-2">
    <b-dropdown-header>Dropdown header</b-dropdown-header>
    <b-dropdown-item-button>First item</b-dropdown-item-button>
    <b-dropdown-item-button>Second Item</b-dropdown-item-button>
  </b-dropdown>
</div>

<!-- b-dropdown-item-header.vue -->

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

<b-dropdown-text>

Place any freeform text within a dropdown menu using the <b-dropdown-text> sub component or use text and use spacing utilities. Note that you’ll likely need additional sizing styles to constrain/set the menu width.

<div>
  <b-dropdown id="ddown-text" text="Dropdown with text" class="m-2">
    <b-dropdown-text style="width: 240px;">
      Some example text that's free-flowing within the dropdown menu.
    </b-dropdown-text>
    <b-dropdown-text>And this is more example text.</b-dropdown-text>
    <b-dropdown-divider />
    <b-dropdown-item-button>First item</b-dropdown-item-button>
    <b-dropdown-item-button>Second Item</b-dropdown-item-button>
  </b-dropdown>
</div>

<!-- b-dropdown-text.vue -->

<b-dropdown-text> has the BootstrapVue custom class .b-dropdown-text applied to it which sets some basic styles which are suitable in most situations. By default it's width will be the same as the widest <b-dropdown-item> content. You may need to place additional styles or helper classes on the component.

By default <b-dropdown-text> renders using tag <p>. You can change the rendered tag by setting the tag prop to any valid HTML5 tag on the <b-dropdown-text> sub-component.

<b-dropdown-form>

Dropdowns support basic forms. Put a <b-dropdown-form> within a dropdown menu and place form controls within the <b-dropdown-form>. The <b-dropdown-form> is based on the <b-form> component, and supports the same props and attributes as a regular form.

<template>
  <div>
    <b-dropdown id="ddown-form" text="Dropdown with form" ref="ddown" class="m-2">
      <b-dropdown-form>
        <b-form-group label="Email" label-for="ddown-form-email">
          <b-form-input size="sm" placeholder="email@example.com" id="ddown-form-email">
          </b-form-input>
        </b-form-group>

        <b-form-group label="Password" label-for="ddown-form-passwd">
          <b-form-input type="password" size="sm" placeholder="Password" id="ddown-form-passwd">
          </b-form-input>
        </b-form-group>

        <b-form-checkbox class="mb-3">Remember me</b-form-checkbox>
        <b-button variant="primary" size="sm" @click="onClick">Sign In</b-button>
      </b-dropdown-form>
      <b-dropdown-divider />
      <b-dropdown-item-button>New around here? Sign up</b-dropdown-item-button>
      <b-dropdown-item-button>Forgot Password?</b-dropdown-item-button>
    </b-dropdown>
  </div>
</template>

<script>
  export default {
    methods: {
      onClick() {
        // Close the menu and (by passing true) return focus to the toggle button
        this.$refs.ddown.hide(true)
      }
    }
  }
</script>

<!-- b-dropdown-form.vue -->

<b-dropdown-form> has the BootstrapVue custom class .b-dropdown-form applied to it which sets some basic styles which are suitable in most situations. By default it's width will be the same as the widest <b-dropdown-item> content. You may need to place additional styles or helper classes on the component.

Closing the menu via form interaction

Clicking buttons inside of a <b-dropdown-form> will not automatically close the menu. If you need to close the menu using a button (or via the form submit event), call the hide() method on the <b-dropdown> instance, as is shown in the above example.

The hide() method accepts a single boolean argument. If the argument is true, then focus will be returned to the dropdown toggle button after the menu has closed. Otherwise the document will gain focus once the menu is closed.

Listening to dropdown changes via $root events

To listen to any dropdown opening, use:

mounted() {
  this.$root.$on('bv::dropdown::show', (bvEvent) => {
    console.log('Dropdown is about to be shown', bvEvent)
  })
}

Refer to the Events section of documentation for the full list of events.

Accessibility

Providing a unique id prop ensures ARIA compliance by automatically adding the appropriate aria-* attributes in the rendered markup.

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 user case.

When a menu item doesn't trigger navigation, it is recommended to use the <b-dropdown-item-button> sub-component (which is not announced as a link) instead of <b-dropdown-item> (which is presented as a link to the user).

When using <b-dropdown-header> 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. To improve on this, wrap the header and related menu items in a <div> with role="group". This will provide users of assistive technologies (i.e. sight-impaired users) additional context about the dropdown item:

<div>
  <b-dropdown id="ddown-aria" text="Dropdown ARIA" variant="primary" class="m-2">
    <div role="group" aria-labelledby="header1">
      <b-dropdown-header id="header1">Groups</b-dropdown-header>
      <b-dropdown-item-button aria-describedby="header1">Add</b-dropdown-item-button>
      <b-dropdown-item-button aria-describedby="header1">Delete</b-dropdown-item-button>
    </div>
    <div role="group" aria-labelledby="header2">
      <b-dropdown-header id="header2">Users</b-dropdown-header>
      <b-dropdown-item-button aria-describedby="header2">Add</b-dropdown-item-button>
      <b-dropdown-item-button aria-describedby="header2">Delete</b-dropdown-item-button>
    </div>
    <b-dropdown-divider />
    <b-dropdown-item-button>
      Something <strong>not</strong> associated with user
    </b-dropdown-item-button>
  </b-dropdown>
</div>

<!-- b-dropdown-aria.vue -->

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

Note that DOWN and UP will not move focus into <b-dropdown-form> sub components, but users can still use TAB or SHIFT+TAB to move into form controls within the menu.

Implementation Note

On touch-enabled devices, opening a <b-dropdown> adds empty (noop) mouseover handlers to the immediate children of the <body> element. This admittedly ugly hack is necessary to work around a quirk in iOS’ event delegation, 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.

See Also

Dropdown Component Reference

<b-dropdown>

Component aliases

<b-dropdown> can also be used via the following aliases:

  • <b-dd>

Properties

PropertyTypeDefault Value
idString
disabledBooleanfalse
textString
htmlString
dropupBooleanfalse
droprightBooleanfalse
dropleftBooleanfalse
rightBooleanfalse
offsetNumber or String0
no-flipBooleanfalse
popper-optsObject
toggle-textStringToggle Dropdown
sizeString
variantString
menu-classString or Array
toggle-tagStringbutton
toggle-classString or Array
no-caretBooleanfalse
splitBooleanfalse
split-hrefString
split-toString or Object
split-variantString
roleStringmenu
boundaryString or ObjectscrollParent

Slots

SlotDescription
button-contentCan be used to implement custom text with icons and more styling.
textDeprecated. please use 'button-content' slot instead.

Events

EventArgumentsDescription
show
bvEvt - BvEvent object. Call bvEvt.preventDefault() to cancel show.
Emitted just before dropdown is shown. Cancelable.
shownEmitted when dropdown is shown.
hide
bvEvt - BvEvent object. Call bvEvt.preventDefault() to cancel hide.
Emitted just before dropdown is hidden. Cancelable.
hiddenEmitted when dropdown is hidden.
toggleEmitted when toggle button is clicked.
clickEmitted when split button is clicked in split mode.

<b-dropdown-item>

Component aliases

<b-dropdown-item> can also be used via the following aliases:

  • <b-dd-item>

Properties

PropertyTypeDefault Value
hrefString
relString
targetString_self
activeBooleanfalse
disabledBooleanfalse
toString or Object
appendBooleanfalse
replaceBooleanfalse
eventString or Arrayclick
active-classString
exactBooleanfalse
exact-active-classString
router-tagStringa
no-prefetchBooleanfalse

Events

EventArgumentsDescription
click
Native click event object
Emitted when item is clicked.

<b-dropdown-item-button>

Component aliases

<b-dropdown-item-button> can also be used via the following aliases:

  • <b-dropdown-item-btn>
  • <b-dd-item-button>
  • <b-dd-item-btn>

Properties

PropertyTypeDefault Value
activeBooleanfalse
active-classStringactive
disabledBooleanfalse

Events

EventArgumentsDescription
click
Native click event object
Emitted when button item is clicked.

<b-dropdown-header>

Component aliases

<b-dropdown-header> can also be used via the following aliases:

  • <b-dd-header>

Properties

PropertyTypeDefault Value
idString
tagStringh6

<b-dropdown-divider>

Component aliases

<b-dropdown-divider> can also be used via the following aliases:

  • <b-dd-divider>

Properties

PropertyTypeDefault Value
tagStringdiv

<b-dropdown-form>

Component aliases

<b-dropdown-form> can also be used via the following aliases:

  • <b-dd-form>

Properties

PropertyTypeDefault Value
idString
inlineBooleanfalse
novalidateBooleanfalse
validatedBooleanfalse

<b-dropdown-text>

Component aliases

<b-dropdown-text> can also be used via the following aliases:

  • <b-dd-text>

Properties

PropertyTypeDefault Value
tagStringp

Importing individual Dropdown Components

ComponentImport Path
<b-dropdown>bootstrap-vue/es/components/dropdown/dropdown
<b-dropdown-item>bootstrap-vue/es/components/dropdown-item/dropdown-item
<b-dropdown-item-button>bootstrap-vue/es/components/dropdown-item-button/dropdown-item-button
<b-dropdown-header>bootstrap-vue/es/components/dropdown-header/dropdown-header
<b-dropdown-divider>bootstrap-vue/es/components/dropdown-divider/dropdown-divider
<b-dropdown-form>bootstrap-vue/es/components/dropdown-form/dropdown-form
<b-dropdown-text>bootstrap-vue/es/components/dropdown-text/dropdown-text

Example:

import BDropdown from 'bootstrap-vue/es/components/dropdown/dropdown'
Vue.component('b-dropdown', BDropdown)

Importing Dropdown as a Vue plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

import { Dropdown } from 'bootstrap-vue/es/components'
Vue.use(Dropdown)