> ## Documentation Index > Fetch the complete documentation index at: https://www.beeq.design/llms.txt > Use this file to discover all available pages before exploring further. # Dropdown > Dropdowns provide users with a compact and organized list of options, actions, or destinations from a trigger. export const CodeLivePreview = ({code, children, height, removePadding = false, mode = 'shadow'}) => { const previewRef = useRef(null); const BEEQ_ESM_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.esm.js'; const BEEQ_CSS_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.css'; const BEEQ_ICONS_URL = 'https://esm.sh/@beeq/core/dist/beeq/svg'; const ensureParentBeeqRuntime = () => { if (document.querySelector('script[data-beeq-parent-runtime]')) return; const script = document.createElement('script'); script.type = 'module'; script.src = BEEQ_ESM_URL; script.dataset.beeqParentRuntime = BEEQ_ICONS_URL; document.head.appendChild(script); }; const executeSnippetScripts = (root, runtimeWindow, previewRootArg, skipAttr) => { root.querySelectorAll('script').forEach(oldScript => { if (skipAttr && oldScript.hasAttribute(skipAttr)) return; if (oldScript.src) { const newScript = runtimeWindow.document.createElement('script'); newScript.src = oldScript.src; oldScript.replaceWith(newScript); return; } runtimeWindow.Function('previewRoot', oldScript.textContent || '')(previewRootArg); oldScript.remove(); }); }; const syncIframeMode = iframeDoc => { const root = document.documentElement; const explicitMode = root.getAttribute('bq-mode'); const isDark = root.classList.contains('dark'); const resolvedMode = explicitMode || (isDark ? 'dark' : 'light'); iframeDoc.documentElement.setAttribute('bq-mode', resolvedMode); iframeDoc.body.setAttribute('bq-mode', resolvedMode); }; useEffect(() => { if (mode === 'shadow') ensureParentBeeqRuntime(); }, [mode]); useEffect(() => { const container = previewRef.current; if (!container) return; if (removePadding) container.style.padding = '0'; container.innerHTML = ''; if (mode === 'iframe') { const iframe = document.createElement('iframe'); iframe.className = 'preview-iframe'; iframe.style.width = '100%'; iframe.style.border = '0'; iframe.style.display = 'block'; iframe.style.minHeight = height ?? '0px'; iframe.setAttribute('title', 'Live code preview'); iframe.setAttribute('loading', 'lazy'); iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin'); container.appendChild(iframe); const iframeDoc = iframe.contentDocument; const iframeWin = iframe.contentWindow; if (!iframeDoc || !iframeWin) return; iframeDoc.open(); iframeDoc.write(['', '', '', ' ', ' ', ' ', ` `, ` `, '', '', code, '', ''].join('\n')); iframeDoc.close(); syncIframeMode(iframeDoc); const modeObserver = new MutationObserver(() => syncIframeMode(iframeDoc)); modeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'bq-mode'] }); executeSnippetScripts(iframeDoc, iframeWin, iframeDoc, 'data-beeq-iframe-runtime'); return () => modeObserver.disconnect(); } const shadowRoot = container.shadowRoot ?? container.attachShadow({ mode: 'open' }); if (!shadowRoot.adoptedStyleSheets.length) { const fixSheet = new CSSStyleSheet(); fixSheet.replaceSync(` bq-dropdown::part(panel), bq-panel::part(panel), bq-select::part(panel), bq-date-picker::part(panel) { z-index: 9999; } bq-tooltip::part(panel) { position: absolute; } `); shadowRoot.adoptedStyleSheets = [fixSheet]; } shadowRoot.innerHTML = [``, code].join(''); executeSnippetScripts(shadowRoot, window, shadowRoot); return undefined; }, [code, mode, height]); return
{}
{} {children &&
{children}
}
; }; BEEQ Dropdown component overview BEEQ Dropdown component overview A dropdown surfaces a floating panel of options, actions, or destinations from a compact trigger. Use one when you need to keep choices accessible without taking over the interface. `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. 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. 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. Enables users to choose one item from a predefined list. Selected choices should be visibly highlighted so users can understand the current value. 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 Dropdown anatomy Dropdown anatomy A dropdown is composed of a trigger and a floating panel. The trigger can be a button, avatar, icon button, or another appropriate interactive element. The panel contains the options or custom content users can act on. | 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 | The panel should contain a list of related options, actions, or destinations. Use [`bq-option-list`](/components/option-list) with [`bq-option`](/components/option) and [`bq-option-group`](/components/option-group) for common dropdown patterns, or add custom content when you need a more specific layout or interaction. ## 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. `bq-dropdown` does not manage chevron rotation automatically. Listen to the `bqOpen` event and update the icon name (`caret-up` / `caret-down`) or apply a CSS rotation on your trigger accordingly. ### 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 a `bq-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. bq-dropdown::part(dropdown) { --bq-panel-z-index: 12; } Dropdown Users My profile Dashboard Settings Logout `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Dropdown Users My profile Dashboard Settings Logout ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqDropdown, BqIcon, BqOption, BqOptionList } from "@beeq/react"; Dropdown Users My profile Dashboard Settings Logout ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqDropdown, BqButton, BqIcon, BqOptionList, BqOption } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqDropdown, BqButton, BqIcon, BqOptionList, BqOption], template: ` Dropdown Users My profile Dashboard Settings Logout `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` 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 the `placement` 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. :host { justify-content: space-around !important; } bq-dropdown::part(dropdown) { --bq-panel-z-index: 12; } Bottom start Users My profile Dashboard Bottom end Users My profile Dashboard `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Bottom start Users My profile Dashboard Bottom end Users My profile Dashboard ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqDropdown, BqIcon, BqOption, BqOptionList } from "@beeq/react"; Bottom start Users My profile Dashboard Bottom end Users My profile Dashboard ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqDropdown, BqButton, BqIcon, BqOptionList, BqOption } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqDropdown, BqButton, BqIcon, BqOptionList, BqOption], template: ` Bottom start Users My profile Dashboard Bottom end Users My profile Dashboard `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### 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. :host { justify-content: space-around !important; } bq-button:has(bq-avatar) { &::part(button) { padding: 0; } &::part(label) { display: flex; align-items: center; } } bq-dropdown::part(dropdown) { --bq-panel-z-index: 12; } Edit Duplicate Archive My profile Settings Logout `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Edit Duplicate Archive My profile Settings Logout ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAvatar, BqButton, BqDropdown, BqIcon, BqOption, BqOptionList } from "@beeq/react"; Edit Duplicate Archive My profile Settings Logout ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqDropdown, BqButton, BqIcon, BqOptionList, BqOption, BqAvatar } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqDropdown, BqButton, BqIcon, BqOptionList, BqOption, BqAvatar], template: ` Edit Duplicate Archive My profile Settings Logout `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Keep open Use `keep-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. bq-dropdown::part(dropdown) { --bq-panel-z-index: 12; } Dropdown Users My profile Dashboard Settings Logout `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Dropdown Users My profile Dashboard Settings Logout ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqDropdown, BqIcon, BqOption, BqOptionList } from "@beeq/react"; Dropdown Users My profile Dashboard Settings Logout ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqDropdown, BqButton, BqIcon, BqOptionList, BqOption } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqDropdown, BqButton, BqIcon, BqOptionList, BqOption], template: ` Dropdown Users My profile Dashboard Settings Logout `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### 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. bq-dropdown::part(dropdown) { --bq-panel-z-index: 12; } Dropdown Configuration Users My profile Settings `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Dropdown Configuration Users My profile Settings ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqDropdown, BqIcon, BqOption, BqOptionGroup, BqOptionList } from "@beeq/react"; Dropdown Configuration Users My profile Settings ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqDropdown, BqButton, BqIcon, BqOptionList, BqOptionGroup, BqOption } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqDropdown, BqButton, BqIcon, BqOptionList, BqOptionGroup, BqOption], template: ` Dropdown Configuration Users My profile Settings `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Panel size Use `same-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. bq-dropdown::part(dropdown) { --bq-panel-z-index: 12; } Choose a region Europe, Middle East & Africa Americas Asia & Pacific `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Choose a region Europe, Middle East & Africa Americas Asia & Pacific ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqDropdown, BqIcon, BqOption, BqOptionList } from "@beeq/react"; Choose a region Europe, Middle East & Africa Americas Asia & Pacific ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqDropdown, BqButton, BqIcon, BqOptionList, BqOption } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqDropdown, BqButton, BqIcon, BqOptionList, BqOption], template: ` Choose a region Europe, Middle East & Africa Americas Asia & Pacific `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Use a `bq-button` as the trigger. It gives users a clear, clickable target and signals that interaction is available. Don't Use a link-style trigger to open the dropdown panel. A dropdown opens a floating surface; it should not look like direct page navigation. Do Use 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't Use the same chevron direction regardless of state. Users rely on the icon direction to understand whether the panel is open or closed. Do Use short, clear labels for both the trigger and each option so users can quickly understand the context and available choices. Don't Use long, vague, or technical labels. They slow users down and increase the risk of selecting the wrong option. Do Arrange options alphabetically or in a meaningful semantic order so users can find what they need without scanning every item. Don't Display 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 `
` element that hosts the trigger element | | `dropdown` | The `bq-panel` element used under the hood to display the dropdown panel | | `panel` | The `
` element used to display and style the panel inside the `bq-panel` element | ### CSS custom properties | Variable | Description | Default | | --------------------------- | --------------------------------- | ------------------------- | | `--bq-panel--background` | Panel background color | `var(--bq-ui--primary)` | | `--bq-panel--border-color` | Panel border color | `transparent` | | `--bq-panel--border-radius` | Panel border radius | `var(--bq-radius--s)` | | `--bq-panel--border-style` | Panel border style | `none` | | `--bq-panel--border-width` | Panel border width | `unset` | | `--bq-panel--box-shadow` | Panel box shadow | `var(--bq-box-shadow--m)` | | `--bq-panel--paddingY` | Vertical padding | `var(--bq-spacing-xs)` | | `--bq-panel--padding-start` | Start padding | `var(--bq-spacing-xs)` | | `--bq-panel--padding-end` | End padding | `var(--bq-spacing-xs)` | | `--bq-panel--height` | Panel max height | `50vh` | | `--bq-panel--width` | Panel width | `320px` | | `--bq-panel-z-index` | Panel z-index applied when opened | `10` | Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties). ## Resources Explore Dropdown examples in Storybook View the dropdown component source on GitHub