Dropdowns

Toggle contextual overlays for links, actions, forms, split buttons, alignment, directions, options, and events.

Overview

Dropdowns are toggleable overlays powered by Bootstrap's dropdown plugin. BCL composes the toggle and menu with bs-dropdown, bs-dropdown-menu, and menu item helpers, while still allowing Bootstrap data attributes for plugin options.

Accessibility

Use dropdowns for action menus or related navigation choices. The toggle exposes expanded state, disabled menu items are removed from keyboard focus, and split buttons need a visible action label plus a visually hidden toggle label.

Bootstrap dropdowns are intentionally generic, so they can contain links, buttons, forms, or other controls. Bootstrap still supports common keyboard interactions such as arrow-key item movement and closing the menu with Escape.

Examples

Use <bs-dropdown> to wrap the toggle content and the captured <bs-dropdown-menu>. Prefer button toggles for actions; anchor toggles should include role information when they act like controls.

Single button

A single <bs-dropdown> can render a dropdown toggle with any supported button variant and a captured menu.

aspnet 

<bs-dropdown btn-style="Secondary">
    Dropdown button
    <bs-dropdown-menu>
        <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#">Something else here</bs-dropdown-menu-item>
    </bs-dropdown-menu>
</bs-dropdown>

Button variants

Use btn-style to apply Bootstrap button variants to the dropdown toggle.

aspnet 

<bs-div display="Flex" gap="Default2" flex-wrap="Wrap">
    <bs-dropdown btn-style="Primary">
        Primary
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Secondary">
        Secondary
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Success">
        Success
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Danger">
        Danger
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Warning">
        Warning
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Info">
        Info
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
</bs-div>

Split button

Set is-split="true" and provide a captured <bs-split-button> when the primary action and menu toggle should be separate hit areas.

aspnet 

<bs-div display="Flex" gap="Default2" flex-wrap="Wrap">
    <bs-dropdown is-split="true" btn-style="Primary">
        Primary
        <bs-split-button>
            <bs-span screen-reader-visibility="VisuallyHidden">Toggle Dropdown</bs-span>
        </bs-split-button>
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Something else here</bs-dropdown-menu-item>
            <bs-dropdown-menu-divider />
            <bs-dropdown-menu-item href="#">Separated link</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown is-split="true" btn-style="Secondary">
        Secondary
        <bs-split-button>
            <bs-span screen-reader-visibility="VisuallyHidden">Toggle Dropdown</bs-span>
        </bs-split-button>
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
            <bs-dropdown-menu-divider />
            <bs-dropdown-menu-item href="#">Separated link</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
</bs-div>

Sizing

Use btn-size on the dropdown helper to size both regular and split button dropdowns.

aspnet 

<bs-div display="Flex" gap="Default2" flex-wrap="Wrap">
    <bs-dropdown btn-style="Secondary" btn-size="Large">
        Large button
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Secondary" btn-size="Small">
        Small button
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
</bs-div>

Directions

Use drop-direction for dropup, centered, dropend, and dropstart menus. Directional start and end behavior follows Bootstrap's RTL-aware direction handling.

aspnet 

<bs-div display="Flex" gap="Default2" flex-wrap="Wrap">
    <bs-dropdown drop-direction="Down" btn-style="Secondary">
        Dropdown
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown drop-direction="Up" btn-style="Secondary">
        Dropup
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown drop-direction="CenteredDown" btn-style="Secondary">
        Centered
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown drop-direction="CenteredUp" btn-style="Secondary">
        Dropup centered
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown drop-direction="End" btn-style="Secondary">
        Dropend
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown drop-direction="Start" btn-style="Secondary">
        Dropstart
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
</bs-div>

Menu alignment

Apply end alignment directly or set breakpoint-specific alignment on the dropdown. BCL forwards alignment to the menu and sets static display where Bootstrap requires it.

aspnet 

<bs-div display="Flex" gap="Default2" flex-wrap="Wrap">
    <bs-dropdown btn-style="Secondary" drop-alignment="End">
        End aligned
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Secondary" drop-alignment="End" drop-alignment-lg="Start">
        End, then lg start
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
</bs-div>

Dark dropdowns

Use the dark menu variant when the dropdown belongs in a dark navbar or dark surface. Keep the toggle, menu, and surrounding color mode aligned so item hover and active states remain legible.

aspnet 

<bs-dropdown btn-style="Secondary">
    Dark menu
    <bs-dropdown-menu dark="true">
        <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#">Something else here</bs-dropdown-menu-item>
        <bs-dropdown-menu-divider />
        <bs-dropdown-menu-item href="#">Separated link</bs-dropdown-menu-item>
    </bs-dropdown-menu>
</bs-dropdown>

Menu items

Dropdown items can render as links, buttons, or non-interactive text. Use the item helper with an href for links and without one for plain dropdown item text.

aspnet 

<bs-dropdown btn-style="Secondary">
    Dropdown
    <bs-dropdown-menu>
        <bs-dropdown-menu-item>Dropdown item text</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#">Something else here</bs-dropdown-menu-item>
    </bs-dropdown-menu>
</bs-dropdown>

Active

Use active state for the current or selected dropdown item and include aria-current when it represents the current page.

aspnet 

<bs-dropdown btn-style="Secondary">
    Active state
    <bs-dropdown-menu>
        <bs-dropdown-menu-item href="#">Regular link</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#" is-active="true" aria-current="Page">Active link</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#">Another link</bs-dropdown-menu-item>
    </bs-dropdown-menu>
</bs-dropdown>

Disabled

Disabled dropdown items are styled as unavailable and removed from normal activation. Do not point disabled menu entries at reachable destinations.

aspnet 

<bs-dropdown btn-style="Secondary">
    Disabled state
    <bs-dropdown-menu>
        <bs-dropdown-menu-item href="#">Regular link</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#" disabled="true">Disabled link</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#">Another link</bs-dropdown-menu-item>
    </bs-dropdown-menu>
</bs-dropdown>

Menu content

Use headers, plain text items, and dividers to structure non-action content inside a dropdown menu. Keep headers descriptive and avoid making divider-only groups the only cue for meaning.

aspnet 

<bs-dropdown btn-style="Secondary">
    Menu content
    <bs-dropdown-menu>
        <bs-dropdown-menu-header>Dropdown header</bs-dropdown-menu-header>
        <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        <bs-dropdown-menu-item>Plain text item</bs-dropdown-menu-item>
        <bs-dropdown-menu-divider />
        <bs-dropdown-menu-item href="#">Separated link</bs-dropdown-menu-item>
    </bs-dropdown-menu>
</bs-dropdown>

Forms

When a form is used as the menu container, BCL applies dropdown menu styling and sets data-bs-auto-close="outside" so clicks inside the form do not immediately close the menu. Keep form controls labeled because the dropdown plugin does not add form semantics.

aspnet 

<bs-dropdown btn-style="Secondary">
    Form menu
    <bs-form x-padding="Default4" y-padding="Default3">
        <bs-floating-label bottom-margin="Default3">
            <bs-label>Email address</bs-label>
            <bs-input input-type="Email" placeholder-text="name@@example.com" />
        </bs-floating-label>
        <bs-floating-label bottom-margin="Default3">
            <bs-label>Password</bs-label>
            <bs-input input-type="Password" placeholder-text="Password" />
        </bs-floating-label>
        <bs-check name="dropdownRememberMe" bottom-margin="Default3">
            Remember me
        </bs-check>
        <bs-button btn-type="Submit" btn-style="Primary">Sign in</bs-button>
    </bs-form>
</bs-dropdown>

Auto close behavior

Use Bootstrap's data-bs-auto-close option to choose whether inside clicks, outside clicks, both, or neither close the menu.

aspnet 

<bs-div display="Flex" gap="Default2" flex-wrap="Wrap">
    <bs-dropdown btn-style="Secondary" data-bs-auto-close="true">
        Default
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Secondary" data-bs-auto-close="inside">
        Inside only
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Secondary" data-bs-auto-close="outside">
        Outside only
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Secondary" data-bs-auto-close="false">
        Manual
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
</bs-div>

Dropdown options

Bootstrap plugin options can be supplied with data attributes when there is no dedicated BCL property. Use data attributes for plugin configuration such as offset, reference element, boundary behavior, and static display.

aspnet 

<bs-div display="Flex" gap="Default2" flex-wrap="Wrap">
    <bs-dropdown btn-style="Secondary" data-bs-offset="10,20">
        Offset 10,20
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown is-split="true" btn-style="Secondary" data-bs-reference="parent">
        Reference parent
        <bs-split-button>
            <bs-span screen-reader-visibility="VisuallyHidden">Toggle Dropdown</bs-span>
        </bs-split-button>
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
    <bs-dropdown btn-style="Secondary" data-bs-display="static">
        Display static
        <bs-dropdown-menu>
            <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
            <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
        </bs-dropdown-menu>
    </bs-dropdown>
</bs-div>

Submenus (BCL extension)

Submenus are not part of upstream Bootstrap 5.3. BCL supports nested dropdown menus as a component extension.

aspnet 

<bs-dropdown btn-style="Secondary">
    With submenu
    <bs-dropdown-menu>
        <bs-dropdown-menu-item href="#">Top action</bs-dropdown-menu-item>
        <bs-dropdown-menu-item>
            More options
            <bs-dropdown-menu>
                <bs-dropdown-menu-item href="#">Sub item 1</bs-dropdown-menu-item>
                <bs-dropdown-menu-item href="#">Sub item 2</bs-dropdown-menu-item>
            </bs-dropdown-menu>
        </bs-dropdown-menu-item>
    </bs-dropdown-menu>
</bs-dropdown>

Usage

Use data attributes for declarative dropdowns. For imperative control, create or retrieve a Bootstrap dropdown instance from the toggle element.

javascript 

const dropdownElementList = document.querySelectorAll('.dropdown-toggle')
const dropdownList = [...dropdownElementList].map(dropdownToggleEl => new bootstrap.Dropdown(dropdownToggleEl))

Options

Common options include autoClose, boundary, display, offset, popperConfig, and reference. Use BCL properties for supported structural concerns and Bootstrap data attributes for plugin options. Separate data attributes override values from data-bs-config when Bootstrap merges configuration.

Methods and events

Dropdown methods are asynchronous and return when a transition starts. Calls made while a dropdown is already transitioning can be ignored by Bootstrap.

aspnet 

<bs-dropdown btn-style="Secondary"
             on-show="console.log('Dropdown show')"
             on-shown="console.log('Dropdown shown')"
             on-hide="console.log('Dropdown hide')"
             on-hidden="console.log('Dropdown hidden')">
    With events
    <bs-dropdown-menu>
        <bs-dropdown-menu-item href="#">Action</bs-dropdown-menu-item>
        <bs-dropdown-menu-item href="#">Another action</bs-dropdown-menu-item>
    </bs-dropdown-menu>
</bs-dropdown>

These map to show.bs.dropdown, shown.bs.dropdown, hide.bs.dropdown, and hidden.bs.dropdown. Event handlers can inspect clickEvent on hide events when Bootstrap supplies it.