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

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

<ExampleSnippet component="DropdownSingleButtonExample" componentName="React Dropdown" />

And with `<a>` elements:

<ExampleSnippet component="DropdownSingleButton2Example" componentName="React Dropdown" />

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

<ExampleSnippet component="DropdownSingleButton3Example" componentName="React Dropdown" />

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

<ExampleSnippet component="DropdownSplitButtonExample" componentName="React Dropdown" />

## Sizing

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

<ExampleSnippet component="DropdownSizingLargeExample" componentName="React Dropdown" />

<ExampleSnippet component="DropdownSizingSmallExample" componentName="React Dropdown" />

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

<ExampleSnippet component="DropdownDarkExample" componentName="React Dropdown" />

And putting it to use in a navbar:

<ExampleSnippet component="DropdownDark2Example" componentName="React Dropdown" />


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

<ExampleSnippet component="DropdownCenteredExample" componentName="React Dropdown" />

### Dropup

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

<ExampleSnippet component="DropdownDropupExample" componentName="React Dropdown" />

### Dropup centered

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

<ExampleSnippet component="DropdownDropupCenteredExample" componentName="React Dropdown" />

### Dropend

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

<ExampleSnippet component="DropdownDropendExample" componentName="React Dropdown" />

### Dropstart

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

<ExampleSnippet component="DropdownDropstartExample" componentName="React Dropdown" />

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

<ExampleSnippet component="DropdownMenuItemsExample" componentName="React Dropdown" />

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

<ExampleSnippet component="DropdownMenuItems2Example" componentName="React Dropdown" />

### Active

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

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

<ExampleSnippet component="DropdownMenuItemsActiveExample" componentName="React Dropdown" />

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

<ExampleSnippet component="DropdownMenuItemsDisabledExample" componentName="React Dropdown" />

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

<ExampleSnippet component="DropdownMenuAlignmentExample" componentName="React Dropdown" />

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

<ExampleSnippet component="DropdownResponsiveAlignmentExample" componentName="React Dropdown" />

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

<ExampleSnippet component="DropdownResponsiveAlignment2Example" componentName="React Dropdown" />


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

<ExampleSnippet component="DropdownMenuContentHeadersExample" componentName="React Dropdown" />

### Dividers

Separate groups of related menu items with a divider.

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

<ExampleSnippet component="DropdownMenuContentDividersExample" componentName="React Dropdown" />

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

<ExampleSnippet component="DropdownMenuContentTextExample" componentName="React Dropdown" />

### Forms

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

<ExampleSnippet component="DropdownMenuContentFormsExample" componentName="React Dropdown" />

## Dropdown options

Use `offset` to displace the dropdown from its default position. The value is a string with two numbers separated by a comma, e.g. `offset={[10, 20]}`. Use `portal` property to render dropdowns in `body` instead of the parent element. This helps to avoid any overflow or z-index issues.

<ExampleSnippet component="DropdownOptionsExample" componentName="React Dropdown" />

### Auto close behavior

By default, dropdowns are closed when clicking outside of the dropdown menu or the toggle button. You can change this behavior with the `autoClose` property. Set `autoClose` to: 

- `true` - Close on clicks inside or outside of the React.js dropdown menu.
- `false` - Disable auto-close; close manually by setting the `visible={false}` (also not closed by `Escape`).
- `'inside'` - Close only when clicking inside the React.js dropdown menu.
- `'outside'` - Close only when clicking outside the React.js dropdown menu.

<ExampleSnippet component="DropdownOptionsAutoCloseBehaviorExample" componentName="React Dropdown" />

## API

Check out the documentation below for a comprehensive guide to all the props you can use with the components mentioned here.

- [&lt;CDropdown /&gt;](./api/#cdropdown)
- [&lt;CDropdownDivider /&gt;](./api/#cdropdowndivider)
- [&lt;CDropdownHeader /&gt;](./api/#cdropdownheader)
- [&lt;CDropdownItem /&gt;](./api/#cdropdownitem)
- [&lt;CDropdownItemPlain /&gt;](./api/#cdropdownitemplain)
- [&lt;CDropdownMenu /&gt;](./api/#cdropdownmenu)
- [&lt;CDropdownToggle /&gt;](./api/#cdropdowntoggle)
