> ## 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 > Options are individual selectable items rendered inside a list, dropdown, or navigation menu, each carrying a label, an optional icon prefix, and an optional icon suffix. 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}
}
; }; export const CardTile = ({title, href, imageLightSrc, imageDarkSrc, children, enableImgZoom}) => { if (!href) { return
{imageLightSrc && {title}} {imageDarkSrc && {title}} {title &&

{title}

}
{children}
; } return {imageLightSrc && {title}} {imageDarkSrc && {title}} {title &&

{title}

}
{children}
; }; BEEQ Option component overview BEEQ Option component overview `bq-option` is a single selectable item inside a list-based UI control such as a dropdown, select, or navigation menu. It manages its own focused, selected, and disabled states, and communicates user interactions back to the parent through events. `bq-option` must always be placed inside a `bq-option-list`, which provides the required `role="listbox"` context. Rendering an option outside a list breaks the ARIA relationship expected by assistive technologies. ## When to use Use options when * You need a single selectable item inside a dropdown, select, or menu * The item requires a text label with optional prefix or suffix icons to add clarity * The choice should be individually disableable without removing it from the list Do not use options when * You need a standalone interactive control — use `bq-button` or `bq-checkbox` instead * The action is destructive and needs confirmation — surface it as a dialog or separate form element, not a list item * The item will be displayed outside a `bq-option-list` context ## Option patterns The simplest form — a text label with no icon. Use for compact menus where space is limited and the labels are self-explanatory. An icon to the left of the label visually categorizes the item. Use when the list contains many entries and users benefit from a quick visual scan. An icon to the right of the label signals a secondary function — such as an external link, a shortcut key, or a status indicator. Use sparingly so it does not compete with the primary label. ## Anatomy BEEQ Option component anatomy BEEQ Option component anatomy Each option is a button-like surface with an optional prefix icon, a label, and an optional suffix icon. The three parts are spaced via dedicated CSS custom properties. | Part | Element | Description | | ----- | ------- | -------------------------------------------------------------- | | **1** | Prefix | Optional slot for an icon or element rendered before the label | | **2** | Label | The main text content of the option | | **3** | Suffix | Optional slot for an icon or element rendered after the label | ## Design guidelines ### States `bq-option` manages hover, focus, selected, and disabled styles automatically via internal CSS. You do not need to apply classes or attributes for these visual states — set the `selected` and `disabled` props and the component handles the rest. Setting `selected="true"` highlights the option with the brand accent color, signaling the current active choice to users. Setting `disabled="true"` mutes the option and blocks click and keyboard events without removing the item from the list. Use this when a choice is contextually unavailable rather than permanently absent. ### Icon placement Place prefix icons when the list is long and icon-based scanning helps users find the right item quickly. Reserve the suffix slot for secondary information — an arrow indicating an external link, a keyboard shortcut, or a status badge — that does not compete with the label. The most common pattern. One icon on the left anchors the visual rhythm of the list and speeds up scanning. Use when the right-aligned indicator is the primary reason for the icon — for example, a link-out arrow that tells users this option opens a new page. Acceptable for rich option lists where both a category icon (prefix) and a status indicator (suffix) genuinely add value. Avoid overusing this combination — it can make the list feel dense. ## Usage ### Default A simple list of options inside a `bq-option-list`. Each option carries a `value` attribute used by the parent to identify which item the user selected. User profile Change password Close session `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} User profile Change password Close session ``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqOption, BqOptionList } from "@beeq/react"; User profile Change password Close session ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqOption, BqOptionList } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqOption, BqOptionList], template: ` User profile Change password Close session `, }) export class DefaultOptionComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### With prefix icon Add a `bq-icon` in the `prefix` slot to give each item a visual anchor. Icons make longer lists easier to scan and help users recognize options without reading every label. User profile Change password Close session `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} User profile Change password 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 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 Close session `, }) export class OptionWithPrefixIconComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### With suffix icon Use the `suffix` slot for a right-aligned secondary indicator. Common uses include link-out arrows, keyboard shortcuts, or status icons. User profile Admin dashboard Change password Close session `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} User profile Admin dashboard Change password Close session ``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqOptionList } from "@beeq/react"; User profile Admin dashboard Change password 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 Admin dashboard Change password Close session `, }) export class OptionWithSuffixIconComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### Selected state Set `selected` on the option that reflects the current active value. The component applies the brand accent styling automatically. User profile Change password Close session `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} User profile Change password 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 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 Close session `, }) export class SelectedOptionComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Disabled state Set `disabled` on individual options to mark them as contextually unavailable. Disabled options remain visible in the list but do not respond to clicks or keyboard events. User profile Admin dashboard Change password Close session `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} User profile Admin dashboard Change password Close session ``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqOptionList } from "@beeq/react"; User profile Admin dashboard Change password 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 Admin dashboard Change password Close session `, }) export class DisabledOptionComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Hidden state Set `hidden` on an option to remove it from the visible list and the accessibility tree while keeping it in the DOM. Unlike `disabled`, a hidden option is completely invisible — screen readers skip it and it cannot be focused. Use this for options that are programmatically toggled based on application state. User profile Change password Close session `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} User profile Change password 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 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 Admin dashboard Change password Close session `, }) export class HiddenOptionComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` To organize options into labeled sections, wrap `bq-option` elements in [`bq-option-group`](/components/option-group) and place the groups inside a `bq-option-list`. The [Option Group](/components/option-group) page has full code examples including header prefix and suffix customization. ## Best practices Do Always provide a `value` attribute on each option so the parent component can identify which item was selected. Don't Omit the `value` attribute. Without it, the parent `bq-option-list` or select-like component cannot distinguish which option the user chose. Do Use `disabled` for options that are temporarily unavailable in the current context — keeping them visible signals that the feature exists. Don't Use `hidden` as a permanent way to remove an option. If an option is never relevant for the user, remove it from the DOM entirely instead. Do Keep option labels short and descriptive — one to four words that clearly identify the action or destination. Don't Write long sentences as option labels. Long labels break the visual rhythm of the list and make scanning harder. Do Use consistent icon placement across all options in the same list — either all with prefix icons or all without. Don't Mix options with icons and options without icons in the same list — the uneven spacing makes the list look misaligned. ## Accessibility `bq-option` sets `role="option"` on its host element automatically. It also manages the following ARIA attributes based on its props: * `aria-selected="true"` is set when `selected` is `true`, communicating the active choice to screen readers. * `aria-disabled` is always present on the host. It is set to `"true"` when `disabled` or `hidden` is `true`, and to `"false"` otherwise, ensuring assistive technologies always have the correct interactive state. * `aria-hidden="true"` is set when `hidden` is `true`, removing the item from the accessibility tree entirely. As a developer, you are responsible for: * **Placing options inside `bq-option-list`** — the `role="option"` on each item requires a `role="listbox"` ancestor, which `bq-option-list` provides. Rendering options outside this context breaks the ARIA relationship. * **Providing meaningful labels** — the text inside the default slot is read by screen readers as the option's accessible name. Avoid icon-only options; always include a visible text label. * **Keyboard navigation** — `bq-option` listens for `Enter` keydown and emits `bqEnter`. The parent `bq-option-list` handles `ArrowUp`/`ArrowDown` focus management. Do not intercept these keys in your own handlers unless you are building a custom container. ## API reference ### Properties | Property | Attribute | Description | Type | Default | | -------------- | --------------- | --------------------------------------------------- | --------- | ------- | | `disabled` | `disabled` | If true, the option is disabled | `boolean` | `false` | | `displayValue` | `display-value` | Overrides the default displayed value of the option | `string` | — | | `hidden` | `hidden` | If true, the option is hidden | `boolean` | `false` | | `selected` | `selected` | If true, the option is selected and active | `boolean` | `false` | | `value` | `value` | A string used to identify the option | `string` | — | ### Events | Event | Description | Type | | --------- | --------------------------------------------------------- | ---------------------------------- | | `bqBlur` | Emitted when the option loses focus | `CustomEvent` | | `bqClick` | Emitted when the option is clicked | `CustomEvent` | | `bqEnter` | Emitted when Enter is pressed while the option is focused | `CustomEvent` | | `bqFocus` | Emitted when the option receives focus | `CustomEvent` | ### Slots | Slot | Description | | ----------- | --------------------------------------------------------- | | *(default)* | The label text content of the option | | `prefix` | Content rendered before the label — typically a `bq-icon` | | `suffix` | Content rendered after the label — typically a `bq-icon` | ### Shadow parts | Part | Description | | -------- | ----------------------------------------------------- | | `base` | The internal `