bq-dropdown needs two slots: trigger for the element users interact with, and the default slot for the panel content. It uses bq-panel under the hood and commonly contains bq-option-list, bq-option, and bq-option-group.When to use
Use dropdowns when
- You have more than 3 options and need to keep the interface compact
- Users need a list of available actions, destinations, or values from a trigger
- The choices are related and can be scanned after opening the panel
- You need a menu, select-like surface, or contextual action list without taking over the page
Do not use dropdowns when
- You have less than 3 options that can stay visible on the page
- The options are critical and should not be hidden behind an extra interaction
- The panel would cover important content, links, buttons, or other active controls
- The list is too long, unclear, or better handled by search, filters, tabs, or a full page flow
Patterns
Dropdowns support compact action menus and panel-based selection patterns.Dropdown
A dropdown is useful for providing users with a list of options in a compact and organized manner. It is primarily used to initiate an action or direct the user to a new page or modal.
Dropdown panel
Serves as a menu presenting a list of available items or actions for users to freely apply or use. The panel slot can host single-select or multi-select forms when the interaction needs it.
Single select
Enables users to choose one item from a predefined list. Selected choices should be visibly highlighted so users can understand the current value.
Multi-select
Allows users to apply more than one choice from the same panel. Use
keep-open-on-select when the dropdown should remain open after each selection.Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Trigger | The slotted element that opens and closes the dropdown |
| 2 | Label | The trigger’s visible text that communicates the dropdown purpose or content |
| 3 | Chevron or cue | Visual indicator that communicates whether the dropdown is open or closed |
| 4 | Panel | The floating surface rendered by bq-panel under the hood |
Design guidelines
Chevron direction
Chevrons on the trigger must reflect the current state of the panel. Use a downward-pointing chevron when the panel is closed, and switch to an upward-pointing chevron when it is open. Reversing this communicates the wrong state to users and erodes trust in the interface.Data ordering
Arrange options alphabetically or by a meaningful semantic order, such as frequency of use or logical progression. A randomly ordered list forces users to scan every item before finding what they need.Usage
Default
The trigger can be any appropriate interactive element, but in most cases abq-button with a bq-icon works well for navigation, selection, or action menus. Use the open attribute when you need to control the visible state.
While the panel is open, the dropdown blocks page scrolling by default. Use
disable-scroll-lock to allow the page to scroll behind it.
If the dropdown sits inside a scrollable area, scrolling that area will close the panel — you can see this behavior on this documentation page.Options
Placement
Use theplacement attribute when you need fine-grained control over the panel position. bottom-start anchors the panel to the start side of the trigger, while bottom-end aligns it to the end side.
Custom trigger
Use a custom trigger when the dropdown needs a more specific visual entry point, such as an icon-only action menu or a profile avatar menu. The trigger must remain understandable and accessible.Keep open
Usekeep-open-on-select when the dropdown should stay open after a selection is made, enabling users to make multiple selections or navigate through related options without reopening the panel each time.
With option group
Use option groups when you need to categorize and group options under specific headers. This gives users a clearer structure when the dropdown contains several related sets of choices.Panel size
Usesame-width when the panel should match the trigger width. Use panel-height to override the panel height when the option list needs a predictable scroll area.
Best practices
DoUse a
bq-button as the trigger. It gives users a clear, clickable target and signals that interaction is available.Don’tUse a link-style trigger to open the dropdown panel. A dropdown opens a floating surface; it should not look like direct page navigation.
DoUse a downward chevron when the panel is closed and an upward chevron when it is open. The chevron should always match the actual state.
Don’tUse the same chevron direction regardless of state. Users rely on the icon direction to understand whether the panel is open or closed.
DoUse short, clear labels for both the trigger and each option so users can quickly understand the context and available choices.
Don’tUse long, vague, or technical labels. They slow users down and increase the risk of selecting the wrong option.
DoArrange options alphabetically or in a meaningful semantic order so users can find what they need without scanning every item.
Don’tDisplay a large, unordered list without structure. If users need search or filtering to navigate the options, consider a more appropriate pattern.
Accessibility
bq-dropdown does not render its own ARIA role — accessible semantics come from the slotted trigger element. When a bq-button is used as the trigger, it exposes role="button" and aria-disabled automatically. The bq-option-list inside the panel renders with role="listbox", and each bq-option carries role="option", aria-selected, and aria-disabled.
Developer responsibilities: provide a meaningful visible label or aria-label on the trigger, especially for icon-only triggers. When using a bq-avatar as the trigger, supply the label prop to ensure screen readers announce the button purpose.
- The dropdown trigger should be reachable with Tab and expose a clear accessible label.
- Users should be able to open the dropdown with Enter or Space when the trigger is focused.
- In selectable lists, users should be able to move between options with arrow keys and select the focused option with Enter or Space.
- Pressing Esc closes the dropdown, and Tab closes it when focus leaves the component.
- For multi-select patterns, selection and deselection should remain visible and predictable.
- Do not rely on icons alone. Pair icon-only triggers with accessible labels and keep option text readable.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
disableScrollLock | disable-scroll-lock | If true, the dropdown panel will not lock the page body scroll when open | boolean | false |
disabled | disabled | If true, the dropdown panel will not be shown | boolean | false |
distance | distance | Represents the distance, gutter, or margin between the panel and the trigger element | number | 4 |
keepOpenOnSelect | keep-open-on-select | If true, the panel will remain open after a selection is made | boolean | false |
open | open | If true, the panel will be visible | boolean | false |
panelHeight | panel-height | When set, it overrides the height of the dropdown panel | string | undefined |
placement | placement | Position of the panel | 'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'bottom-start' |
sameWidth | same-width | Whether the panel should have the same width as the trigger element | boolean | false |
skidding | skidding | Represents the skidding between the panel and the trigger element | number | 0 |
strategy | strategy | Defines the positioning strategy | 'fixed' | 'absolute' | 'fixed' |
Events
| Event | Description | Type |
|---|---|---|
bqOpen | Emitted when the dropdown panel is opened or closed | CustomEvent<{ open: boolean }> |
Slots
| Slot | Description |
|---|---|
| (default) | The content of the dropdown panel |
trigger | The trigger element that opens the dropdown panel |
Shadow parts
| Part | Description |
|---|---|
base | The component’s internal wrapper |
trigger | The <div> element that hosts the trigger element |
dropdown | The bq-panel element used under the hood to display the dropdown panel |
panel | The <div> element used to display and style the panel inside the bq-panel element |
CSS custom properties
Resources
Interactive playground
Explore Dropdown examples in Storybook
Source code
View the dropdown component source on GitHub