> ## 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. # Option List > Option List is a listbox container that groups one or more Option items and surfaces a selection event when the user clicks or activates any of them. 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 Option List component overview BEEQ Option List component overview `bq-option-list` is the required wrapper for `bq-option` and `bq-option-group` elements. It sets the `role="listbox"` context, handles keyboard and click events from child options, and emits a single `bqSelect` event with the selected item's value back to the parent component. `bq-option-list` is a structural container — it does not render any visible UI of its own. It is used internally by higher-level components such as `bq-select` and `bq-dropdown`. Use it directly only when you are building a custom listbox-based control. ## When to use Use option list when * You are composing a custom dropdown, command palette, or navigation menu from `bq-option` items * You need a `role="listbox"` container that bubbles selection events from child options to your component logic * You want to combine flat options with `bq-option-group` sections in the same list Do not use option list when * You are using `bq-select` or `bq-dropdown` — these components manage `bq-option-list` internally * You need a multi-select list with checkboxes — use form controls such as `bq-checkbox` directly * The items are primarily navigational links rather than discrete selectable choices ## Option List patterns A plain sequence of `bq-option` items. Use when all choices belong to the same category and no visual separation is needed. One or more `bq-option-group` containers inside the list. Use when choices fall into distinct named categories that help users scan faster. Ungrouped options above or below grouped sections. Use when a "pinned" set of common choices (for example, "Recently used") should appear before the full categorized list. ## Anatomy BEEQ Option List component anatomy BEEQ Option List component anatomy `bq-option-list` is a single flex column container that holds slotted option items or option groups. It has no visual chrome of its own — the border, shadow, and background typically come from the enclosing panel or dropdown trigger. | Part | Element | Description | | ----- | ------------ | ------------------------------------------------------------------------------- | | **1** | Base | The internal `
` that stacks slotted options vertically with consistent gap | | **2** | Option items | `bq-option` or `bq-option-group` elements placed in the default slot | ## Design guidelines ### Use with a containing surface `bq-option-list` provides layout and interaction semantics but no background or border. Wrap it in a surface element — typically a panel, popover, or card — that provides the visual boundary users associate with a dropdown or list. When used inside `bq-select` or `bq-dropdown`, the containing surface is handled automatically. The guidelines here apply when you are building a custom container from scratch. ### Vertical rhythm The gap between items is controlled by the `--bq-option-group--gapY-list` CSS custom property. The default is tight (`var(--bq-spacing-xs)`) to keep the list compact. Increase it only when items are taller than a single text line or when the list is used in a context with generous surrounding whitespace. ### Accessible label The `ariaLabel` prop (rendered as `aria-label` on the host element) names the listbox for screen readers. The default value is `"Options"`. Override it with a more specific label when the context makes the default ambiguous — for example, `"Navigation links"` or `"Assignees"`. ## Usage ### Flat list A simple list with no groups. Each `bq-option` carries a `value` so the parent can identify the selection via the `bqSelect` event. User profile Change password Settings Close session `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} User profile Change password Settings Close session ``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqOptionList } from "@beeq/react"; User profile Change password Settings Close session ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqOptionList } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqOptionList], template: ` User profile Change password Settings Close session `, }) export class FlatOptionListComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` To use grouped sections, place [`bq-option-group`](/components/option-group) elements inside `bq-option-list`. The `bqSelect` event still bubbles from whichever `bq-option` the user activates. See the [Option Group](/components/option-group) page for full grouped list examples including header prefix and suffix slots. ## Options ### Custom accessible label Override `aria-label` when the default `"Options"` is too generic for the context. A specific label helps screen reader users understand the purpose of the list before navigating into it. Home Dashboard Reports `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Home Dashboard Reports ``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqOptionList } from "@beeq/react"; Home Dashboard Reports ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqOptionList } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqOptionList], template: ` Home Dashboard Reports `, }) export class AccessibleOptionListComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Always place `bq-option` and `bq-option-group` directly inside `bq-option-list` — the component listens for `bqClick` and `bqEnter` events from child options and will not receive them if additional wrapper elements break the event path. Don't Wrap options in arbitrary `
` or `` elements inside the list. Non-option wrappers break the `bqClick`/`bqEnter` event delegation that `bq-option-list` relies on to emit `bqSelect`. Do Override `aria-label` with a descriptive phrase when the list is not the only `role="listbox"` on the page or when the default `"Options"` does not communicate the list's purpose. Don't Leave the default `aria-label="Options"` on multiple lists within the same view without making each one contextually unique — screen reader users navigating by landmark will see identical labels and cannot tell the lists apart. Do Listen to the `bqSelect` event on `bq-option-list` rather than individual `bqClick` events on each `bq-option`. The list normalises both click and Enter-key activations into a single `bqSelect` event with a consistent `{ value, item }` payload. Don't Attach separate `bqClick` listeners to every `bq-option` when you only need the selected value — `bq-option-list` already aggregates these and emitting redundant handlers increases the chance of inconsistent state. Do Use `bq-option-group` to divide a long list into named sections when the number of items makes scanning difficult. Don't Render dozens of flat options without any grouping. An ungrouped list longer than around eight items becomes hard to scan — users have to read every item individually rather than jumping to the relevant category. ## Accessibility `bq-option-list` sets `role="listbox"` on its host element during `componentDidLoad`. This establishes the ARIA container that child `bq-option` elements (which carry `role="option"`) require in order to form a valid accessible list. The `ariaLabel` prop is reflected as `aria-label` on the host and defaults to `"Options"`. It names the listbox for assistive technologies. As a developer, you are responsible for: * **Providing a meaningful `ariaLabel`** when the default is ambiguous. Screen readers announce the listbox name before a user navigates into it, so a specific label ("Assignees", "Color palette") is more useful than the generic default. * **Placing only `bq-option` and `bq-option-group` elements inside the list** — inserting non-option elements breaks the `role="listbox"` / `role="option"` relationship that assistive technologies expect. * **Managing focus** when the list is shown or hidden — `bq-option-list` does not manage focus automatically. If you are building a custom dropdown, move focus to the first option when the list opens and return it to the trigger when it closes. ## API reference ### Properties | Property | Attribute | Description | Type | Default | | ----------- | ------------ | -------------------------------- | -------- | ----------- | | `ariaLabel` | `aria-label` | Accessible label for the listbox | `string` | `'Options'` | ### Events | Event | Description | Type | | ---------- | --------------------------------------------------------- | ----------------------------------------------------------- | | `bqSelect` | Emitted when an option is selected via click or Enter key | `CustomEvent<{ value: string; item: HTMLBqOptionElement }>` | ### Slots | Slot | Description | | ----------- | --------------------------------------- | | *(default)* | `bq-option` and `bq-option-group` items | ### Shadow parts | Part | Description | | ------ | ----------------------------------------------------------------- | | `base` | The internal `
` wrapper that stacks slotted items vertically | ### CSS custom properties | Variable | Description | Default | | ------------------------------ | -------------------------------------- | ---------------------- | | `--bq-option-group--gapY-list` | Vertical gap between items in the list | `var(--bq-spacing-xs)` | Learn more about [styling with shadow parts](/guides/styles) and [CSS custom properties](/theming/global-css-variables). ## Resources Explore option list variants and states in Storybook View the component source on GitHub