Bootstrap Vue Dropdown Component

Bootstrap Vue dropdown component allows you to toggle contextual overlays for displaying lists, links, and more html elements.

On this page

Overview

Dropdowns are toggleable, contextual overlays for displaying lists of links and more.

Dropdowns are built on a third party library, Popper.jsopen in new window, which provides dynamic positioning and viewport detection. Popper.js isn't used to position dropdowns in navbars though as dynamic positioning isn't required.

Examples

Bind the dropdown's toggle and the dropdown menu inside <CDropdown>, or different element that declares position: relative;. Dropdowns can be triggered from <a> or <button> elements to better fit your possible requirements.

Single button

Here's how you can put them to work with either <button> elements:

<CDropdown color="secondary">
  <CDropdownToggle color="primary">Dropdown Button</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
  </CDropdownMenu>
</CDropdown>

1
2
3
4
5
6
7
8

And with <a> elements:

<CDropdown color="secondary" togglerText="Dropdown button">
  <CDropdownToggle component="a" color="primary">Dropdown Button</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
  </CDropdownMenu>  
</CDropdown>

1
2
3
4
5
6
7
8

The best part is you can do this with any button variant, too:

<template v-for="(item) in ['primary', 'secondary', 'success', 'info', 'warning', 'danger']">
  <CDropdown :color="item" :togglerText="item" variant="btn-group">
    <CDropdownToggle :color="item">{{togglerText}}</CDropdownToggle>
    <CDropdownMenu>
      <CDropdownItem href="#">Action</CDropdownItem>
      <CDropdownItem href="#">Another action</CDropdownItem>
      <CDropdownItem href="#">Something else here</CDropdownItem>
    </CDropdownMenu>
  </CDropdown>
</template>

1
2
3
4
5
6
7
8
9
10

Split button

Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of boolean prop split for proper spacing around the dropdown caret.

We use this extra class to reduce the horizontal padding on either side of the caret by 25% and remove the margin-left that's attached for normal button dropdowns. Those additional changes hold the caret centered in the split button and implement a more properly sized hit area next to the main button.

<template v-for="(item) in ['primary', 'secondary', 'success', 'info', 'warning', 'danger']">
  <CDropdown :color="item" :togglerText="item" variant="btn-group">
    <CButton :color="item">{{ item }}</CButton>
    <CDropdownToggle :color="item" split>{{item}}</CDropdownToggle>
    <CDropdownMenu>
      <CDropdownItem href="#">Action</CDropdownItem>
      <CDropdownItem href="#">Another action</CDropdownItem>
      <CDropdownItem href="#">Something else here</CDropdownItem>
    </CDropdownMenu>
  </CDropdown>
</template>

1
2
3
4
5
6
7
8
9
10
11

Sizing

Button dropdowns work with buttons of all sizes, including default and split dropdown buttons.

<CDropdown variant="btn-group">
  <CDropdownToggle color="secondary" size="lg">Large button</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>
<CDropdown variant="btn-group">
  <CButton color="secondary" size="lg">Large split button</CButton>
  <CDropdownToggle color="secondary" size="lg" split>Large button</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<CDropdown variant="btn-group">
  <CDropdownToggle color="secondary" size="sm">Small button</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>
<CDropdown variant="btn-group">
  <CButton color="secondary" size="sm">Small split button</CButton>
  <CDropdownToggle color="secondary" size="sm" split>Small button</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Dark dropdowns

Opt into darker dropdowns to match a dark navbar or custom style by set dark property. No changes are required to the dropdown items.

<CDropdown color="secondary" dark>
  <CDropdownToggle color="primary">Dropdown Button</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>

1
2
3
4
5
6
7
8
9
10

And putting it to use in a navbar:

<CNavbar expand="lg" color-scheme="dark" class="bg-dark">
  <CContainer fluid>
    <CNavbarBrand href="#">Navbar</CNavbarBrand>
    <CNavbarNav>
      <CDropdown dark variant="nav-item">
        <CDropdownToggle color="primary">Dropdown Button</CDropdownToggle>
        <CDropdownMenu>
          <CDropdownItem href="#">Action</CDropdownItem>
          <CDropdownItem href="#">Another action</CDropdownItem>
          <CDropdownItem href="#">Something else here</CDropdownItem>
          <CDropdownDivider/>
          <CDropdownItem href="#">Separated link</CDropdownItem>
        </CDropdownMenu>
      </CDropdown>
    </CNavbarNav>
  </CContainer>
</CNavbar>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Directions

RTL

Directions are mirrored when using Bootstrap Vue in RTL, meaning `.dropstart` will appear on the right side.

<CDropdown color="secondary" direction="dropup">
  <CDropdownToggle color="secondary">Dropup</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>
<CDropdown color="secondary" direction="dropup">
  <CButton color="secondary">Split dropup</CButton>
  <CDropdownToggle color="secondary" split/>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Dropright

Trigger dropdown menus at the right of the elements by adding direction="dropend" to the <CDropdown> component.

<CDropdown color="secondary" direction="dropend">
  <CDropdownToggle color="secondary">Dropend</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>
<CDropdown color="secondary" direction="dropend">
  <CButton color="secondary">Split dropend</CButton>
  <CDropdownToggle color="secondary" split/>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Dropleft

Trigger dropdown menus at the left of the elements by adding direction="dropstart" to the <CDropdown> component.

<CDropdown color="secondary" direction="dropstart">
  <CDropdownToggle color="secondary">Dropstart</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>
<CButtonGroup>
  <CDropdown color="secondary" direction="dropstart">
    <CDropdownToggle color="secondary" split/>
    <CDropdownMenu>
      <CDropdownItem href="#">Action</CDropdownItem>
      <CDropdownItem href="#">Another action</CDropdownItem>
      <CDropdownItem href="#">Something else here</CDropdownItem>
      <CDropdownDivider/>
      <CDropdownItem href="#">Separated link</CDropdownItem>
    </CDropdownMenu>
  </CDropdown>
  <CButton color="secondary">Split dropstart</CButton>
</CButtonGroup>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Responsive alignment

If you use responsive alignment, dynamic positioning is disabled.

To align right the dropdown menu with the given breakpoint or larger, add aligment="xs|sm|md|lg|xl|xxl: end".

<CDropdown color="secondary" :alignment="{ 'lg': 'end' }">
  <CDropdownToggle color="secondary">Left-aligned but right aligned when large screen</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>

1
2
3
4
5
6
7
8
9
10

To align left the dropdown menu with the given breakpoint or larger, add aligment="xs|sm|md|lg|xl|xxl: start".

<CDropdown color="secondary" :alignment="{ 'xs': 'end', 'lg': 'start' }">
  <CDropdownToggle color="secondary">Right-aligned but left aligned when large screen</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
    <CDropdownDivider/>
    <CDropdownItem href="#">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>

1
2
3
4
5
6
7
8
9
10

Headers

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

In the following example we use div instead of <CDropdownMenu> to show <CDropdownMenu> content.

<CDropdownHeader>Dropdown header</CDropdownHeader>
<CDropdownItem href="#">Action</CDropdownItem>
<CDropdownItem href="#">Another action</CDropdownItem>

1
2
3

Dividers

Separate groups of related menu items with a divider.

In the following example we use div instead of <CDropdownMenu> to show <CDropdownMenu> content.

<CDropdownItem href="#">Action</CDropdownItem>
<CDropdownItem href="#">Another action</CDropdownItem>
<CDropdownItem href="#">Something else here</CDropdownItem>
<CDropdownDivider/>
<CDropdownItem href="#">Separated link</CDropdownItem>

1
2
3
4
5

Text

Place any freeform text within a dropdown menu with text. Note that you'll likely need additional sizing styles to constrain the menu width.

Some example text that's free-flowing within the dropdown menu.

And this is more example text.

<p>
  Some example text that's free-flowing within the dropdown menu.
</p>
<p class="mb-0">
  And this is more example text.
</p>

1
2
3
4
5
6

Forms

Put a form within a dropdown menu, or make it into a dropdown menu.

<CForm class="px-4 py-4">
  <div class="mb-3">
    <CFormLabel for="exampleDropdownFormEmail1">Email address</CFormLabel>
    <CFormInput type="email" id="exampleDropdownFormEmail1" placeholder="[email protected]"/>
  </div>
  <div class="mb-3">
    <CFormLabel for="exampleDropdownFormPassword1">Password</CFormLabel>
    <CFormInput type="password" id="exampleDropdownFormPassword1" placeholder="Password"/>
  </div>
  <div class="mb-3">
    <CFormCheck id="dropdownCheck" label="Remember me"/>
  </div>
  <CButton type="submit">Sign in</CButton>
</CForm>
<CDropdownDivider/>
<CDropdownItem href="#">New around here? Sign up</CDropdownItem>
<CDropdownItem href="#">Forgot password?</CDropdownItem>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

API

CDropdown

import { CDropdown } from '@coreui/bootstrap-vue'
// or
import CDropdown from '@coreui/bootstrap-vue/src/components/dropdown/CDropdown'

1
2
3

Props

Prop name	Description	Type	Values	Default
alignment	Set aligment of dropdown menu.	string\|object	`{ 'start' \| 'end' \| { xs: 'start' \| 'end' } \| { sm: 'start' \| 'end' } \| { md: 'start' \| 'end' } \| { lg: 'start' \| 'end' } \| { xl: 'start' \| 'end'} \| { xxl: 'start' \| 'end'} }`	-
dark	Sets a darker color scheme to match a dark navbar.	boolean	-
direction	Sets a specified direction and location of the dropdown menu.	string	`'dropup'`, `'dropend'`, `'dropstart'`	-
disabled	Toggle the disabled state for the component.	boolean	-
placement	Describes the placement of your component after Popper.js has applied all the modifiers that may have flipped or altered the originally provided placement property.	Placement	`'auto'`, `'top-end'`, `'top'`, `'top-start'`, `'bottom-end'`, `'bottom'`, `'bottom-start'`, `'right-start'`, `'right'`, `'right-end'`, `'left-start'`, `'left'`, `'left-end'`	'bottom-start'
popper	If you want to disable dynamic positioning set this property to `true`.	boolean	-	true
trigger	Sets which event handlers you’d like provided to your toggle prop. You can specify one trigger or an array of them.	string\|array	-	'click'
variant	Set the dropdown variant to an btn-group, dropdown, input-group, and nav-item.	string	`'btn-group'`, `'dropdown'`, `'input-group'`, `'nav-item'`	'btn-group'
visible	Toggle the visibility of dropdown menu component.	boolean	-

Events

Event name	Description	Properties
hide	Callback fired when the component requests to be hidden.
show	Callback fired when the component requests to be shown.

CDropdownHeader

import { CDropdownHeader } from '@coreui/bootstrap-vue'
// or
import CDropdownHeader from '@coreui/bootstrap-vue/src/components/dropdown/CDropdownHeader'

1
2
3

Props

Prop name	Description	Type	Values	Default
component	Component used for the root node. Either a string to use a HTML element or a component.	string	-	'h6'

CDropdownItem

import { CDropdownItem } from '@coreui/bootstrap-vue'
// or
import CDropdownItem from '@coreui/bootstrap-vue/src/components/dropdown/CDropdownItem'

1
2
3

Props

Prop name	Description	Type	Values	Default
active	Toggle the active state for the component.	boolean	-
component	Component used for the root node. Either a string to use a HTML element or a component.	string	-	'a'
disabled	Toggle the disabled state for the component.	boolean	-
href	The href attribute specifies the URL of the page the link goes to.	string	-	-

CDropdownMenu

import { CDropdownMenu } from '@coreui/bootstrap-vue'
// or
import CDropdownMenu from '@coreui/bootstrap-vue/src/components/dropdown/CDropdownMenu'

1
2
3

Props

Prop name	Description	Type	Values	Default
component	Component used for the root node. Either a string to use a HTML element or a component.	string	`'div'`, `'ul'`	'div'

CDropdownToggle

import { CDropdownToggle } from '@coreui/bootstrap-vue'
// or
import CDropdownToggle from '@coreui/bootstrap-vue/src/components/dropdown/CDropdownToggle'

1
2
3

Props

Prop name	Description	Type	Values	Default
active	Toggle the active state for the component.	boolean	-	false
color	* Sets the color context of the component to one of Bootstrap Vue’s themed colors.	string	`'primary'`, `'secondary'`, `'success'`, `'danger'`, `'warning'`, `'info'`, `'dark'`, `'light'`
caret	Enables pseudo element caret on toggler.	boolean	-	true
component	Component used for the root node. Either a string to use a HTML element or a component.	string	-	'button'
disabled	Toggle the disabled state for the component.	boolean	-
size	Size the component small or large.	string	`'sm'`, `'lg'`	-
split	Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of `.dropdown-toggle-split` className for proper spacing around the dropdown caret.	boolean	-
variant	Set the button variant to an outlined button or a ghost button.	string	`'ghost'`, `'outline'`	-

Bootstrap Vue Dropdown Component

Overview #

Examples #

Single button #

Split button #

Sizing #

Dark dropdowns #

Directions #

RTL

Dropright #

Dropleft #

Responsive alignment #

Menu content #

Headers #

Dropdown header

Dividers #

Text #

Forms #

API #

CDropdown #

Props #

Events #

CDropdownHeader #

Props #

CDropdownItem #

Props #

CDropdownMenu #

Props #

CDropdownToggle #

Props #

Overview

Examples

Single button

Split button

Sizing

Dark dropdowns

Directions

Dropright

Dropleft

Responsive alignment

Menu content

Headers

Dividers

Text

Forms

API

CDropdown

Props

Events

CDropdownHeader

Props

CDropdownItem

Props

CDropdownMenu

Props

CDropdownToggle

Props