Breaking Changes: This page contains breaking changes. Please read the change log carefully.

Dropdown button

The guideline content on this page is synced with Figma and can be used as a source of truth. Open in Figma

A dropdown button shows a list of commands when activated; selecting one performs that command immediately. A dropdown item is a specific action a user can take, presented within a list of similar options.

Anatomy

Button
Arrow icon
Dropdown content
Scrollbar

States

The dropdown button can have the following states.

Enabled
Hover
Pressed
Selected
Disabled
Focused

The static .hover, .focus, and .pressed helper classes (inherited from .btn) render each state without user interaction; the .open class on the wrapping .dropdown renders the Selected state.

development/documentation/docs/dropdown-button/examples/medium-states.html

<div class="d-flex flex-wrap gap-16 align-items-start">
	<div class="dropdown">
		<button type="button" id="dropdown-state-enabled-md" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Enabled</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-enabled-md" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown">
		<button type="button" id="dropdown-state-hover-md" class="btn dropdown-toggle hover" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Hover</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-hover-md" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown">
		<button type="button" id="dropdown-state-pressed-md" class="btn dropdown-toggle pressed" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-pressed="true">Pressed</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-pressed-md" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown open docs-force-open">
		<button type="button" id="dropdown-state-selected-md" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true">Selected state</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-selected-md" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown disabled">
		<button type="button" id="dropdown-state-disabled-md" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" disabled aria-disabled="true">Disabled</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-disabled-md" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown">
		<button type="button" id="dropdown-state-focused-md" class="btn dropdown-toggle focus" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Focused</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-focused-md" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>
</div>

Small

Example
HTML

development/documentation/docs/dropdown-button/examples/small-states.html

<div class="d-flex flex-wrap gap-16 align-items-start">
	<div class="dropdown">
		<button type="button" id="dropdown-state-enabled-sm" class="btn btn-sm dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Enabled</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-enabled-sm" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown">
		<button type="button" id="dropdown-state-hover-sm" class="btn btn-sm dropdown-toggle hover" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Hover</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-hover-sm" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown">
		<button type="button" id="dropdown-state-pressed-sm" class="btn btn-sm dropdown-toggle pressed" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-pressed="true">Pressed</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-pressed-sm" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown open docs-force-open">
		<button type="button" id="dropdown-state-selected-sm" class="btn btn-sm dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true">Selected state</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-selected-sm" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown disabled">
		<button type="button" id="dropdown-state-disabled-sm" class="btn btn-sm dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" disabled aria-disabled="true">Disabled</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-disabled-sm" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown">
		<button type="button" id="dropdown-state-focused-sm" class="btn btn-sm dropdown-toggle focus" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Focused</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-focused-sm" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>
</div>

Sizes

We have two different sizes for our dropdown buttons (Medium and Small). They are designed so you can adjust the size of their content, ensuring visual balance. While their sizing can vary by context, they have a standard default size used throughout the product.

Medium (default) — 40 px tall
Small — 32 px tall, add .btn-sm to the trigger

Example
HTML

development/documentation/docs/dropdown-button/examples/sizes.html

<div class="d-flex flex-wrap gap-16 align-items-start">
	<div class="dropdown">
		<button type="button" id="dropdown-size-medium" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Medium</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-size-medium" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>

	<div class="dropdown">
		<button type="button" id="dropdown-size-small" class="btn btn-sm dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Small</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-size-small" aria-label="Dropdown options">
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
			<li class="dropdown-item"><a href="#!">List item</a></li>
		</ul>
	</div>
</div>

Usage

Use a dropdown button when you have 5 to 15 items for users to choose from. They are ideal for navigation or command menus where the trigger initiates a specific action.

Content guidelines

Keep dropdown items to a single line of text.
Use sentence case for all labels.

Example
HTML

development/documentation/docs/dropdown-button/examples/usage.html

<div class="dropdown">
	<button type="button" id="dropdown-usage" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Settings</button>
	<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-usage" aria-label="Settings options">
		<li class="dropdown-item"><a href="#!">Change language</a></li>
		<li class="dropdown-item"><a href="#!">Notifications</a></li>
		<li class="dropdown-item"><a href="#!">Time zone</a></li>
		<li class="dropdown-item"><a href="#!">Password &amp; security</a></li>
		<li class="dropdown-item"><a href="#!">Support</a></li>
	</ul>
</div>

Accessibility

Keyboard interaction

All components should be reachable via TAB and SHIFT+TAB keys.

Example
HTML

development/documentation/docs/dropdown-button/examples/keyboard-interaction.html

<div class="dropdown">
	<button type="button" id="dropdown-keyboard" class="btn dropdown-toggle focus" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown menu</button>
	<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-keyboard" aria-label="Dropdown options">
		<li class="dropdown-item"><a href="#!">List item</a></li>
		<li class="dropdown-item"><a href="#!">List item</a></li>
		<li class="dropdown-item"><a href="#!">List item</a></li>
	</ul>
</div>

Nested menus

When designing nested menus, try to limit them to two layers. Menus with more layers than that can be difficult for users to navigate and operate.

Best practices

Icon usage

Example
HTML

development/documentation/docs/dropdown-button/examples/best-practice-icons-do.html

<div class="d-flex flex-wrap gap-128">
	<div class="dropdown open docs-force-open" data-dropdown-persistent-open>
		<button type="button" id="dropdown-icons-do-1" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true">Manage</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-icons-do-1" aria-label="Manage options">
			<li class="dropdown-item"><a href="#!"><span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-plus"></span> Add new row</a></li>
			<li class="dropdown-item"><a href="#!"><span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-edit"></span> Edit row</a></li>
			<li class="dropdown-item"><a href="#!"><span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-delete"></span> Delete row</a></li>
		</ul>
	</div>

	<div class="dropdown open docs-force-open" data-dropdown-persistent-open>
		<button type="button" id="dropdown-icons-do-2" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true">Manage</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-icons-do-2" aria-label="Manage options">
			<li class="dropdown-item"><a href="#!">Add new row</a></li>
			<li class="dropdown-item"><a href="#!">Edit row</a></li>
			<li class="dropdown-item"><a href="#!">Delete row</a></li>
		</ul>
	</div>
</div>

Use icons consistently. This keeps text aligned, making the list of options easier for the eye to scan.

Example
HTML

development/documentation/docs/dropdown-button/examples/best-practice-icons-dont.html

<div class="d-flex flex-wrap gap-128">
	<div class="dropdown open docs-force-open" data-dropdown-persistent-open>
		<button type="button" id="dropdown-icons-dont-1" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true">Manage</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-icons-dont-1" aria-label="Manage options">
			<li class="dropdown-item"><a href="#!">Add new row</a></li>
			<li class="dropdown-item"><a href="#!">Edit row</a></li>
			<li class="dropdown-item"><a href="#!"><span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-delete"></span> Delete row</a></li>
		</ul>
	</div>

	<div class="dropdown open docs-force-open" data-dropdown-persistent-open>
		<button type="button" id="dropdown-icons-dont-2" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true">Manage</button>
		<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-icons-dont-2" aria-label="Manage options">
			<li class="dropdown-item"><a href="#!"><span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-plus"></span> Add new row</a></li>
			<li class="dropdown-item"><a href="#!"><span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-edit"></span> Edit row</a></li>
			<li class="dropdown-item"><a href="#!">Delete row</a></li>
		</ul>
	</div>
</div>

Don't

Avoid inconsistent icon use within the same list.

Specs

Dropdown button specifications showing 40 px height, 12 px horizontal padding and 8 px corner radius

Developer reference

The following sections describe supported functionality that is not part of the Figma design specification.

Wrap a .btn.dropdown-toggle in a .dropdown container, followed by a .dropdown-menu list of items. The menu reveals when the toggle is activated.

Use the static .active class on a menu item (and aria-selected="true") to mark the currently chosen option. Mix .divider rows between groups of items.

Example
HTML

development/documentation/docs/dropdown-button/examples/single-button-dropdown.html

<div class="dropdown">
	<button type="button" id="dropdownButton1" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown menu</button>
	<ul class="dropdown-menu" role="menu" aria-expanded="false" aria-hidden="true" aria-labelledby="dropdownButton1" aria-label="Dropdown options">
		<li class="dropdown-item"><a href="#!">Item 1</a></li>
		<li class="dropdown-item active"><a href="#!" aria-selected="true">Item 2, with a loooong label</a></li>
		<li class="dropdown-item disabled"><a tabindex="-1" aria-disabled="true">Item 3</a></li>
		<li class="dropdown-item"><a href="#!">Item 4</a></li>
		<li class="divider"></li>
		<li class="dropdown-item"><a href="#!">Item 5</a></li>
	</ul>
</div>

Add the .disabled class to the wrapping .dropdown (or set the disabled attribute on the trigger button) to render the disabled state. The menu cannot be opened while disabled.

Example
HTML

development/documentation/docs/dropdown-button/examples/single-button-dropdown-disabled.html

<div class="dropdown disabled">
	<button type="button" id="dropdownMenuButton2" class="btn dropdown-toggle" data-toggle="dropdown" tabindex="-1" aria-disabled="true" aria-haspopup="true" aria-expanded="false">Dropdown menu</button>
	<ul class="dropdown-menu" role="menu" aria-expanded="false" aria-hidden="true" aria-labelledby="dropdownMenuButton2">
		<li class="dropdown-item"><a href="#!" tabindex="-1" aria-disabled="true">Item 1</a></li>
		<li class="dropdown-item"><a href="#!" tabindex="-1" aria-disabled="true">Item 2</a></li>
		<li class="dropdown-item"><a href="#!" tabindex="-1" aria-disabled="true">Item 3</a></li>
	</ul>
</div>

Drop-up

Use .dropup on the wrapper to open the menu above the trigger. The chevron points down when the menu is closed and up when it is open, the same as the standard dropdown — it indicates the open / closed state, not the direction the menu expands.

Example
HTML

development/documentation/docs/dropdown-button/examples/drop-up.html

<div class="dropup">
	<button type="button" id="dropdownDropupButton" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown menu</button>
	<ul class="dropdown-menu" role="menu" aria-expanded="false" aria-hidden="true" aria-labelledby="dropdownDropupButton">
		<li class="dropdown-item"><a href="#!">Item 1</a></li>
		<li class="dropdown-item"><a href="#!">Item 2</a></li>
		<li class="dropdown-item"><a href="#!">Item 3</a></li>
	</ul>
</div>

When the menu contains more items than fit within the Figma-mandated max-height: 280px, the menu scrolls vertically and a scrollbar appears on the right edge. No additional markup is needed — the scroll behaviour is provided by the base .dropdown-menu rule (overflow: clip auto).

Example
HTML

development/documentation/docs/dropdown-button/examples/scrollable-menu.html

<div class="dropdown open docs-force-open">
	<button type="button" id="dropdown-scrollable" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true">Settings</button>
	<ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-scrollable" aria-label="Settings options">
		<li class="dropdown-item"><a href="#!">Account</a></li>
		<li class="dropdown-item"><a href="#!">Profile</a></li>
		<li class="dropdown-item"><a href="#!">Preferences</a></li>
		<li class="dropdown-item"><a href="#!">Notifications</a></li>
		<li class="dropdown-item"><a href="#!">Privacy</a></li>
		<li class="dropdown-item"><a href="#!">Security</a></li>
		<li class="dropdown-item"><a href="#!">Billing</a></li>
		<li class="dropdown-item"><a href="#!">Subscription</a></li>
		<li class="dropdown-item"><a href="#!">API keys</a></li>
		<li class="dropdown-item"><a href="#!">Integrations</a></li>
		<li class="dropdown-item"><a href="#!">Audit log</a></li>
		<li class="dropdown-item"><a href="#!">Support</a></li>
		<li class="dropdown-item"><a href="#!">Sign out</a></li>
	</ul>
</div>