---
title: React Dropdown Component
name: Dropdown
description: React dropdown component allows you to toggle contextual overlays for displaying lists, links, and more html elements.
menu: Components
route: /components/dropdown
other_frameworks: dropdown
---

import {
  CButton,
  CButtonGroup,
  CCollapse,
  CContainer,
  CDropdown,
  CDropdownDivider,
  CDropdownHeader,
  CDropdownItem,
  CDropdownItemPlain,
  CDropdownMenu,
  CDropdownToggle,
  CForm,
  CFormCheck,
  CFormInput,
  CFormLabel,
  CNavbar,
  CNavbarBrand,
  CNavbarNav,
  CNavbarToggler,
} from '@coreui/react/src/index'

## Overview

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

Dropdowns are built on a third party library, [Popper.js](https://popper.js.org/), 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:

```jsx preview
<CDropdown>
  <CDropdownToggle color="secondary">Dropdown button</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
  </CDropdownMenu>
</CDropdown>
```

And with `<a>` elements:

```jsx preview
<CDropdown>
  <CDropdownToggle href="#" color="secondary">Dropdown button</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem href="#">Action</CDropdownItem>
    <CDropdownItem href="#">Another action</CDropdownItem>
    <CDropdownItem href="#">Something else here</CDropdownItem>
  </CDropdownMenu>
</CDropdown>
```

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

<Example>
  <>
    {['primary', 'secondary', 'success', 'info', 'warning', 'danger'].map((color, index) => (
      <CDropdown variant="btn-group" key={index}>
        <CDropdownToggle color={color}>{color}</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>
    ))}
  </>
</Example>

```jsx
<>
  {['primary', 'secondary', 'success', 'info', 'warning', 'danger'].map((color, index) => (
    <CDropdown variant="btn-group" key={index}>
      <CDropdownToggle color={color}>{color}</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>
  ))}
</>
```

### 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.

<Example>
  <>
    {['primary', 'secondary', 'success', 'info', 'warning', 'danger'].map((color, index) => (
      <CDropdown variant="btn-group" key={index}>
        <CButton color={color}>{color}</CButton>
        <CDropdownToggle color={color} 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>
    ))}
  </>
</Example>

```jsx
<>
  {['primary', 'secondary', 'success', 'info', 'warning', 'danger'].map((color, index) => (
    <CDropdown variant="btn-group" key={index}>
      <CButton color={color}>{color}</CButton>
      <CDropdownToggle color={color} 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>
  ))}
</>
```

## Sizing

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

```jsx preview
  <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/>
    <CDropdownMenu>
      <CDropdownItem href="#">Action</CDropdownItem>
      <CDropdownItem href="#">Another action</CDropdownItem>
      <CDropdownItem href="#">Something else here</CDropdownItem>
      <CDropdownDivider/>
      <CDropdownItem href="#">Separated link</CDropdownItem>
    </CDropdownMenu>
  </CDropdown>
```

```jsx preview
  <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/>
    <CDropdownMenu>
      <CDropdownItem href="#">Action</CDropdownItem>
      <CDropdownItem href="#">Another action</CDropdownItem>
      <CDropdownItem href="#">Something else here</CDropdownItem>
      <CDropdownDivider/>
      <CDropdownItem href="#">Separated link</CDropdownItem>
    </CDropdownMenu>
  </CDropdown>
```

## 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.

```jsx preview
<CDropdown dark>
  <CDropdownToggle color="secondary">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>
```

And putting it to use in a navbar:

```jsx preview
<CNavbar expand="lg" colorScheme="dark" className="bg-dark">
  <CContainer fluid>
    <CNavbarBrand href="#">Navbar</CNavbarBrand>
    <CNavbarToggler aria-label="Toggle navigation" aria-expanded={true} />
    <CCollapse className="navbar-collapse" visible={true}>
      <CNavbarNav>
        <CDropdown dark as="li" variant="nav-item">
          <CDropdownToggle color="dark">Dropdown</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>
    </CCollapse>
  </CContainer>
</CNavbar>
```

## Directions

<Callout color="info" title="RTL">
  Directions are mirrored when using CoreUI in RTL, meaning `.dropstart` will appear on the right side.
</Callout>

### Centered

Make the dropdown menu centered below the toggle by adding `direction="center"` to the `<CDropdown>` component.

```jsx preview
<CDropdown variant="btn-group" direction="center">
  <CDropdownToggle color="secondary">Centered dropdown</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>
```

### Dropup

Trigger dropdown menus above elements by adding `direction="dropup"` to the `<CDropdown>` component.

```jsx preview
  <CDropdown variant="btn-group" direction="dropup">
    <CDropdownToggle color="secondary">Dropdown</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" direction="dropup">
    <CButton color="secondary" >Small split button</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>
```

### Dropup centered

Make the dropup menu centered above the toggle by adding `direction="dropup-center"` to the `<CDropdown>` component.

```jsx preview
<CDropdown variant="btn-group" direction="dropup-center">
  <CDropdownToggle color="secondary">Centered 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>
```

### Dropend

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

```jsx preview
  <CDropdown variant="btn-group" direction="dropend">
    <CDropdownToggle color="secondary">Dropdown</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" direction="dropend">
    <CButton color="secondary" >Small split button</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>
```

### Dropstart

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

```jsx preview
  <CDropdown variant="btn-group" direction="dropstart">
    <CDropdownToggle color="secondary">Dropdown</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 variant="btn-group" 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" >Small split button</CButton>
  </CButtonGroup>
```

## Menu items

Historically dropdown menu contents _had_ to be links, but that's no longer the case with v4. Now you can optionally use `<button>` elements in your dropdowns instead of just `<a>`s.

```jsx preview
<CDropdown>
  <CDropdownToggle color="secondary">Dropdown</CDropdownToggle>
  <CDropdownMenu>
    <CDropdownItem as="button">Action</CDropdownItem>
    <CDropdownItem as="button">Another action</CDropdownItem>
    <CDropdownItem as="button">Something else here</CDropdownItem>
    <CDropdownDivider />
    <CDropdownItem as="button">Separated link</CDropdownItem>
  </CDropdownMenu>
</CDropdown>
```

You can also create non-interactive dropdown items with `<CDropdownItemPlain>`.

```jsx preview
<CDropdownMenu>
  <CDropdownItemPlain>Dropdown item text</CDropdownItemPlain>
  <CDropdownItem href="#">Action</CDropdownItem>
  <CDropdownItem href="#">Another action</CDropdownItem>
  <CDropdownItem href="#">Something else here</CDropdownItem>
</CDropdownMenu>
```

### Active

Set boolean property `active` to **style item as active**.

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

```jsx preview
<CDropdownMenu>
  <CDropdownItem href="#">Regular link</CDropdownItem>
  <CDropdownItem href="#" active>Active link</CDropdownItem>
  <CDropdownItem href="#">Another link</CDropdownItem>
</CDropdownMenu>
```

### Disabled

Add `disabled` boolean property to items in the dropdown to **style them as disabled**.

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

```jsx preview
<CDropdownMenu>
  <CDropdownItem href="#">Regular link</CDropdownItem>
  <CDropdownItem href="#" disabled>Disabled link</CDropdownItem>
  <CDropdownItem href="#">Another link</CDropdownItem>
</CDropdownMenu>
```

## Menu alignment

By default, a dropdown menu is automatically positioned 100% from the top and along the left side of its parent. Add `aligment="end"` to right align the dropdown menu.

<Callout color="info">
  <strong>Heads up!</strong> Dropdowns are positioned thanks to Popper.
</Callout>

```jsx preview
<CDropdown alignment="end">
  <CDropdownToggle color="secondary">Right-aligned menu example</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>
```

### 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"`.

```jsx preview
<CDropdown 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>
```

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

```jsx preview
<CDropdown 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>
```

## Menu content

### 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.

```jsx preview
<CDropdownMenu>
  <CDropdownHeader>Dropdown header</CDropdownHeader>
  <CDropdownItem href="#">Action</CDropdownItem>
  <CDropdownItem href="#">Another action</CDropdownItem>
</CDropdownMenu>
```

### Dividers

Separate groups of related menu items with a divider.

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

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

### 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.

```jsx preview
<CDropdownMenu className="p-4 text-body-secondary" style={{ maxWidth: '200px' }}>
  <p>Some example text that's free-flowing within the dropdown menu.</p>
  <p className="mb-0">And this is more example text.</p>
</CDropdownMenu>
```

### Forms

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

```jsx preview
<CDropdownMenu>
  <CForm className="px-4 py-4">
    <div className="mb-3">
      <CFormLabel htmlFor="exampleDropdownFormEmail1">Email address</CFormLabel>
      <CFormInput type="email" id="exampleDropdownFormEmail1" placeholder="email@example.com" />
    </div>
    <div className="mb-3">
      <CFormLabel htmlFor="exampleDropdownFormPassword1">Password</CFormLabel>
      <CFormInput type="password" id="exampleDropdownFormPassword1" placeholder="Password" />
    </div>
    <div className="mb-3">
      <CFormCheck id="dropdownCheck" label="Remember me" />
    </div>
    <CButton color="primary" type="submit">Sign in</CButton>
  </CForm>
  <CDropdownDivider />
  <CDropdownItem href="#">New around here? Sign up</CDropdownItem>
  <CDropdownItem href="#">Forgot password?</CDropdownItem>
</CDropdownMenu>
```

## Customizing

### CSS variables

React dropdowns use local CSS variables on `.dropdown` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

<ScssDocs file="_dropdown.scss" capture="dropdown-css-vars"/>

Customization through CSS variables can be seen on the `.dropdown-menu-dark` class where we override specific values without adding duplicate CSS selectors.

<ScssDocs file="_dropdown.scss" capture="dropdown-dark-css-vars"/>

#### How to use CSS variables

```jsx
const vars = { 
  '--my-css-var': 10,
  '--my-another-css-var': "red" 
}
return <CDropdown style={vars}>...</CDropdown>
```

### SASS variables

<ScssDocs file="_variables.scss" capture="dropdown-variables"/>

Variables for the dark dropdown:

<ScssDocs file="_variables.scss" capture="dropdown-dark-variables"/>

Variables for the CSS-based carets that indicate a dropdown's interactivity:

<ScssDocs file="_variables.scss" capture="caret-variables"/>

## API

### CDropdown

`markdown:CDropdown.api.mdx`

### CDropdownDivider

`markdown:CDropdownDivider.api.mdx`

### CDropdownHeader

`markdown:CDropdownHeader.api.mdx`

### CDropdownItem

`markdown:CDropdownItem.api.mdx`

### CDropdownItemPlain

`markdown:CDropdownItemPlain.api.mdx`

### CDropdownMenu

`markdown:CDropdownMenu.api.mdx`

### CDropdownToggle

`markdown:CDropdownToggle.api.mdx`
