> ## 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. # Select > The select input lets users choose one or more options from a predefined list, commonly used in forms for easy data selection. 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 Select component overview BEEQ Select component overview The select input lets users choose one option — or multiple options when `multiple` is enabled — from a predefined list. It pairs a styled trigger with a floating panel of `bq-option` elements and integrates with native HTML forms. ## When to use Use Select when * The option list contains more than five items and a radio group would take too much space * Users need to choose from a predefined set of values in a form * Multiple selection from a long list is required and a checkbox group would be impractical * The available choices are dynamic or loaded from an external source Do not use Select when * Fewer than five options are available — use radio buttons or a segmented control instead * The user needs to type a free-form value not constrained to a fixed list — use an [Input](/components/input) instead * The choices are binary (yes / no, on / off) — use a [Checkbox](/components/checkbox) or toggle instead ## Patterns Single Select allows the user to pick one option from a menu. Multiple Select allows the user to pick multiple options from a menu via checkboxes. Once selected, the items are shown as dismissible tags in the input field above. ## Anatomy BEEQ Select component anatomy BEEQ Select component anatomy The select is composed of a label, an input field, a dropdown panel, and optional status indicators. | Part | Element | Description | | ------ | ----------------------------- | ------------------------------------------------------------------------------ | | **1** | Label | The descriptive label rendered above the input control | | **2** | Input field | The control area that displays the selected value or placeholder | | **3** | Leading icon | Optional prefix icon displayed at the start of the input field | | **4** | Placeholder | The hint text shown inside the input when no value is selected | | **5** | Dropdown panel | The floating container that opens below the input and holds the option list | | **6** | Menu | The list of selectable `bq-option` items inside the dropdown panel | | **7** | Scroll | The scrollbar that appears when the option list overflows the panel height | | **8** | Dropdown icon | The chevron caret at the end of the input that indicates the open/closed state | | **9** | Field status label (optional) | Helper text below the input providing guidance or validation feedback | | **10** | Info label (icon) | Optional icon accompanying the field status label for additional context | ## Design guidelines ### Single vs. multiple selection The default mode. Users pick exactly one option; the selected value replaces the placeholder text in the input. Enable with `multiple`. Selected items appear as removable tags inside the input. Use `max-tags-visible` to cap how many tags show before a `+N` overflow tag appears. ### Validation states Set `validation-status="error"` and populate the `helper-text` slot with the reason. Always pair a visual indicator with a text description so color-blind users are not excluded. Set `validation-status="success"` to confirm a valid selection. Use sparingly — only when confirmation meaningfully reduces user uncertainty. ## Usage ### Default Enhance user interaction by implementing the default select variant. Perfect for scenarios where you want users to choose from a list of options within a dropdown. bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Open Use the `open` attribute to display the select dropdown by default, offering users quick access to the available options without additional clicks. Use `autofocus` to keep the input focused on render. bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Initial value Set an initial `value` for the select component to preselect an option, providing a streamlined user experience and minimizing manual input. bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Display value The `displayValue` property (`display-value` attribute) on `bq-option` overrides the value shown inside the input after selection. Use it when the full option content (e.g., multi-line layout) should not be collapsed into the input field. bq-select::part(panel) { z-index: 12; } .payment-option { display: flex; flex-direction: column; gap: var(--bq-spacing-xs2); } .payment-option__header { display: flex; align-items: center; gap: var(--bq-spacing-xs); } .payment-option__name { font-weight: 600; } .payment-option__meta, .payment-option__owner { padding-inline-start: 28px; color: var(--bq-text--secondary); } .payment-option__meta { font-size: var(--bq-font-size--s); } .payment-option__owner { font-size: var(--bq-font-size--xs); } You will not be charged until you review your order on the next page
Visa ending in 1234
Expires 12/2025 John Doe
Mastercard ending in 5678
Expires 08/2026 Jane Smith
Pay with PayPal
john.doe@email.com
`} > ```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} .payment-option { display: flex; flex-direction: column; gap: var(--bq-spacing-xs2); } .payment-option__header { display: flex; align-items: center; gap: var(--bq-spacing-xs); } .payment-option__name { font-weight: 600; } .payment-option__meta, .payment-option__owner { padding-inline-start: 28px; color: var(--bq-text--secondary); } .payment-option__meta { font-size: var(--bq-font-size--s); } .payment-option__owner { font-size: var(--bq-font-size--xs); } ``` ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} You will not be charged until you review your order on the next page
Visa ending in 1234
Expires 12/2025 John Doe
Mastercard ending in 5678
Expires 08/2026 Jane Smith
Pay with PayPal
john.doe@email.com
``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; import "./styles.css"; You will not be charged until you review your order on the next page
Visa ending in 1234
Expires 12/2025 John Doe
Mastercard ending in 5678
Expires 08/2026 Jane Smith
Pay with PayPal
john.doe@email.com
``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` You will not be charged until you review your order on the next page
Visa ending in 1234
Expires 12/2025 John Doe
Mastercard ending in 5678
Expires 08/2026 Jane Smith
Pay with PayPal
john.doe@email.com
`, styles: [` .payment-option { display: flex; flex-direction: column; gap: var(--bq-spacing-xs2); } .payment-option__header { display: flex; align-items: center; gap: var(--bq-spacing-xs); } .payment-option__name { font-weight: 600; } .payment-option__meta, .payment-option__owner { padding-inline-start: 28px; color: var(--bq-text--secondary); } .payment-option__meta { font-size: var(--bq-font-size--s); } .payment-option__owner { font-size: var(--bq-font-size--xs); } `], }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Disabled Employ the `disabled` attribute to restrict user interaction with the select component temporarily, useful for scenarios where certain options are unavailable. bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Multiple Use the `multiple` property to enable multiple selections. Use `keep-open-on-select` to keep the panel open while the user selects options. The `max-tags-visible` attribute controls how many tags are shown before a `+N` overflow tag appears. bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Running Hiking Biking Swimming Pizza Hamburger `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Running Hiking Biking Swimming Pizza Hamburger ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Running Hiking Biking Swimming Pizza Hamburger ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Running Hiking Biking Swimming Pizza Hamburger ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### Prefix Use the `prefix` slot to include additional visual elements or context, such as an icon, to provide users with extra visual cues about the field's purpose. bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Suffix Leverage the `suffix` slot to enhance the select component with extra elements. The default suffix is a rotating chevron caret; replace it with any icon to match your design context. bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Validation Use `validation-status` to signal the validation state (`error`, `warning`, or `success`) of the select component, ensuring accurate data input and real-time feedback. :host { gap: var(--bq-spacing-l) !important; } bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 Helper text Option 1 Option 2 Option 3 Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 Helper text Option 1 Option 2 Option 3 Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 Helper text Option 1 Option 2 Option 3 Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Option 1 Option 2 Option 3 Helper text Option 1 Option 2 Option 3 Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Label with "Optional" Choose this style when you want to include an optional label for additional context, providing users with guidance while maintaining a clean and unobtrusive design. bq-select::part(panel) { z-index: 12; } div { display: flex; flex: 1 1 0%; } div > label { display: flex; flex-grow: 1; align-items: center; } div > span { color: var(--bq-text--secondary); } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); }
Optional
Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Optional
Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react";
Optional
Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: `
Optional
Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Label with "Info Tooltip" Enhance user understanding by incorporating a `bq-tooltip` alongside the label, offering additional information or clarification about the select. bq-select::part(panel) { z-index: 12; } bq-tooltip { margin-inline-start: var(--bq-spacing-xs); } div { display: flex; flex: 1 1 0%; } div > label { display: flex; flex-grow: 1; align-items: center; } div > span { color: var(--bq-text--secondary); } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); }
Optional
Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Optional
Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect, BqTooltip } from "@beeq/react";
Optional
Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect, BqTooltip], template: `
Optional
Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Panel placement Adjust the panel placement to suit your layout. Use the `placement` attribute to position the dropdown relative to the input — useful when the select is near the bottom of the viewport. bq-select::part(panel) { z-index: 12; } bq-tooltip { margin-inline-start: var(--bq-spacing-xs); } label { display: flex; flex-grow: 1; align-items: center; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect, BqTooltip } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect, BqTooltip], template: ` Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### With no label Use this style when you prefer a minimal look and the field's purpose is conveyed by surrounding context — for example, inside a table or toolbar where a visible label would be redundant. bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### With no Helper Text Select this variant when you don't need additional helper text, giving users a straightforward and uncluttered experience. bq-select::part(panel) { z-index: 12; } Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Readonly A readonly select shows the current value but prevents the panel from opening. Use it in review or summary screens where the displayed value is informational and should not be changed. bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Without clear button Set `disable-clear` to hide the clear button and prevent one-click deselection. Use this when selecting a value is required and removing it should not be trivially easy. bq-select::part(panel) { z-index: 12; } span { display: flex; align-items: center; gap: var(--bq-spacing-xs); } Helper text Option 1 Option 2 Option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Helper text Option 1 Option 2 Option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqSelect } from "@beeq/react"; Helper text Option 1 Option 2 Option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect], template: ` Helper text Option 1 Option 2 Option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Custom behavior Call `preventDefault()` on the `bqInput` event to take full control of option filtering. This lets you implement async filtering, loading states, empty-state messages, and matched-text highlighting entirely in your own code. Set `debounce-time` to throttle how often `bqInput` fires while the user types — `300` ms is a good default for async requests. Running Hiking Biking Swimming Pizza Hamburger Cookie Ice-cream `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Running Hiking Biking Swimming Pizza Hamburger Cookie Ice-cream ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { useState } from 'react'; import type { BqSelectCustomEvent } from '@beeq/core'; import { BqIcon, BqOption, BqSelect, BqSpinner } from '@beeq/react'; const ALL_OPTIONS = [ { label: 'Running', value: 'running', icon: 'sneaker-move', displayValue: 'Running' }, { label: 'Hiking', value: 'hiking', icon: 'boot', displayValue: 'Hiking' }, { label: 'Biking', value: 'biking', icon: 'person-simple-bike', displayValue: 'Biking' }, { label: 'Swimming', value: 'swimming', icon: 'swimming-pool', displayValue: 'Swimming' }, { label: 'Pizza', value: 'pizza', icon: 'pizza', displayValue: 'Pizza' }, { label: 'Hamburger', value: 'hamburger', icon: 'hamburger', displayValue: 'Hamburger' }, { label: 'Cookie', value: 'cookie', icon: 'cookie', displayValue: 'Cookie' }, { label: 'Ice-cream', value: 'ice-cream', icon: 'ice-cream', displayValue: 'Ice-cream' }, ]; function highlight(text: string, query: string) { return text.replace(new RegExp(`(${query})`, 'gi'), '$1'); } export default function App() { const [visibleOptions, setVisibleOptions] = useState(ALL_OPTIONS); const [isLoading, setIsLoading] = useState(false); const [error, setError] = useState(null); const handleInput = async (event: BqSelectCustomEvent<{ value: string }>) => { event.preventDefault(); const query = event.detail.value; if (!query) { setVisibleOptions(ALL_OPTIONS); setError(null); return; } setIsLoading(true); setError(null); try { // Simulate an async API call await new Promise((resolve) => setTimeout(resolve, 300)); const q = query.toLowerCase(); setVisibleOptions( ALL_OPTIONS .filter((o) => o.label.toLowerCase().includes(q)) .map((o) => ({ ...o, label: highlight(o.label, query) })) ); } catch { setError('Error loading options'); } finally { setIsLoading(false); } }; const handleSelect = () => { setVisibleOptions(ALL_OPTIONS); setError(null); }; return ( {isLoading ? ( Loading... ) : error ? ( {error} ) : visibleOptions.length === 0 ? ( No results found ) : ( visibleOptions.map((option) => ( )) )} ); } ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqSelect, BqSpinner } from "@beeq/angular/standalone"; import type { BqSelectCustomEvent } from "@beeq/core"; const ALL_OPTIONS = [ { label: 'Running', value: 'running', icon: 'sneaker-move', displayValue: 'Running' }, { label: 'Hiking', value: 'hiking', icon: 'boot', displayValue: 'Hiking' }, { label: 'Biking', value: 'biking', icon: 'person-simple-bike', displayValue: 'Biking' }, { label: 'Swimming', value: 'swimming', icon: 'swimming-pool', displayValue: 'Swimming' }, { label: 'Pizza', value: 'pizza', icon: 'pizza', displayValue: 'Pizza' }, { label: 'Hamburger', value: 'hamburger', icon: 'hamburger', displayValue: 'Hamburger' }, { label: 'Cookie', value: 'cookie', icon: 'cookie', displayValue: 'Cookie' }, { label: 'Ice-cream', value: 'ice-cream', icon: 'ice-cream', displayValue: 'Ice-cream' }, ]; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqSelect, BqSpinner], template: ` @if (isLoading) { Loading... } @else { @if (visibleOptions.length === 0) { No results found } @for (option of visibleOptions; track option.value) { } } ` }) export class AppComponent { visibleOptions = [...ALL_OPTIONS]; isLoading = false; handleInput(event: BqSelectCustomEvent<{ value: string }>): void { event.preventDefault(); const query = event.detail.value; if (!query) { this.visibleOptions = [...ALL_OPTIONS]; return; } this.isLoading = true; const q = query.toLowerCase(); setTimeout(() => { this.isLoading = false; this.visibleOptions = ALL_OPTIONS .filter((o) => o.label.toLowerCase().includes(q)) .map((o) => ({ ...o, label: o.label.replace(new RegExp(`(${query})`, 'gi'), '$1'), })); }, 300); } handleSelect(): void { this.visibleOptions = [...ALL_OPTIONS]; } } ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Form integration `bq-select` is form-associated, so it participates in native submission, reset, and required validation. Use `name` for the submitted key, `required` for browser validation, and `form-validation-message` for a custom native validation message. body { padding: var(--bq-spacing-l); } .select-form { display: grid; gap: var(--bq-spacing-m); } .select-form__actions { display: flex; gap: var(--bq-spacing-s); justify-content: flex-end; } .select-form__output { margin: 0; padding: var(--bq-spacing-s); border: var(--bq-stroke-s) solid var(--bq-stroke--tertiary); border-radius: var(--bq-radius--s); background: var(--bq-ui--secondary); color: var(--bq-text--primary); white-space: pre-wrap; }
Choose the plan that matches your expected response time. Standard Priority Enterprise
Reset Submit 
{}
`} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Choose the plan that matches your expected response time. Standard Priority Enterprise Reset Submit 
{}
``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { useState } from "react"; import { BqButton, BqOption, BqSelect } from "@beeq/react"; export default function SelectForm() { const [data, setData] = useState("{}"); return (
setData("{}")} onSubmit={(event) => { event.preventDefault(); setData(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget).entries()), null, 2)); }} > Choose the plan that matches your expected response time. Standard Priority Enterprise Reset Submit 
{data}
); } ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqOption, BqSelect } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqOption, BqSelect], template: `
Choose the plan that matches your expected response time. Standard Priority Enterprise Reset Submit 
{{ data }}
`, }) export class SelectFormComponent { data = "{}"; handleSubmit(event: SubmitEvent): void { event.preventDefault(); this.data = JSON.stringify(Object.fromEntries(new FormData(event.target as HTMLFormElement).entries()), null, 2); } } ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Always populate the `label` slot so the select has an accessible name visible to all users, not just those relying on assistive technology. Don't Leave the `label` slot empty and rely solely on `placeholder` text — placeholder disappears once a value is selected and is not announced reliably by screen readers. Do Write a clear, neutral placeholder such as "Choose a country" so users understand the field is interactive and what kind of value they are selecting. Don't Use the placeholder as a label substitute or write a directive like "Select" without context — this gives users no information about what the field is for. Do Use `validation-status` and the `helper-text` slot together when the field is required or has a validation error, so users understand exactly what is wrong and how to fix it. Don't Apply `validation-status="error"` without a helper text message — a red border alone does not tell users what is wrong or how to correct it. Do Provide meaningful option labels that describe the value clearly — e.g., "Europe" instead of "EU", "Pro plan (\$49/mo)" instead of "pro". Don't Use internal codes, abbreviations, or IDs as the visible option labels — what is meaningful in your database is not necessarily meaningful to users. ## Accessibility * **Built in:** the native `` inside the control has `role="combobox"`, `aria-haspopup="listbox"`, `aria-expanded` (toggled when the panel opens and closes), and `aria-controls` pointing to the `bq-option-list` by `id`. * **Built in:** `aria-disabled="true"` is applied on the input when `disabled` is set. * **Built in:** the component is form-associated via `ElementInternals`, so it works with native `
` elements, `required` validation, and `formResetCallback`. * **Built in:** keyboard navigation — `Tab` moves focus to the input; `Enter` / `Space` opens the panel; `ArrowDown` / `ArrowUp` move between options; `Enter` selects the focused option; `Escape` closes the panel. * **Built in:** in multi-select mode, `Backspace` on an empty input removes the most recently added tag. * **Your responsibility:** always provide a visible label via the `label` slot. The `aria-labelledby` on the combobox role relies on the label element being present. * **Your responsibility:** when `validation-status` is `"error"`, populate the `helper-text` slot with a clear error description so `aria-describedby` can link the input to the explanation. * **Your responsibility:** if options are loaded asynchronously, provide a loading indicator in the panel slot so users know content is arriving. ## API reference ### Properties | Property | Attribute | Description | Type | Default | | ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | `autofocus` | `autofocus` | If `true`, the Select input will be focused on component render | `boolean` | — | | `clearButtonLabel` | `clear-button-label` | The aria label for the clear button | `string` | `'Clear value'` | | `debounceTime` | `debounce-time` | Milliseconds to wait before emitting `bqInput` after typing | `number` | `0` | | `disableClear` | `disable-clear` | If `true`, the clear button is hidden | `boolean` | `false` | | `disabled` | `disabled` | If `true`, the select cannot be interacted with | `boolean` | `false` | | `disableScrollLock` | `disable-scroll-lock` | If `true`, the page body scroll will not be locked when the panel is open | `boolean` | `false` | | `distance` | `distance` | Gap in pixels between the panel and the input element | `number` | `8` | | `form` | `form` | The `id` of the `` element this select belongs to | `string` | — | | `formValidationMessage` | `form-validation-message` | Native validation message used when `required` is set | `string` | — | | `keepOpenOnSelect` | `keep-open-on-select` | If `true`, the panel stays open after a selection | `boolean` | `false` | | `maxTagsVisible` | `max-tags-visible` | Maximum number of tags shown in multi-select mode before a `+N` tag appears | `number` | `2` | | `multiple` | `multiple` | If `true`, the select allows multiple selections | `boolean` | `false` | | `name` | `name` | The form control name, submitted as part of a name/value pair. **Required** for form submission | `string` | — | | `open` | `open` | If `true`, the panel is visible | `boolean` | `false` | | `panelHeight` | `panel-height` | Overrides the default height of the Select panel | `string` | — | | `placeholder` | `placeholder` | Placeholder text shown when no value is selected | `string` | — | | `placement` | `placement` | Position of the Select panel relative to the input | `'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start'` | `'bottom'` | | `readonly` | `readonly` | If `true`, the option list cannot be opened or filtered | `boolean` | — | | `required` | `required` | If `true`, a value must be selected before the form can be submitted | `boolean` | — | | `sameWidth` | `same-width` | If `true`, the panel matches the width of the input element | `boolean` | `true` | | `skidding` | `skidding` | Offset in pixels along the input element axis | `number` | `0` | | `strategy` | `strategy` | CSS position strategy used to place the panel | `'fixed' \| 'absolute'` | `'fixed'` | | `validationStatus` | `validation-status` | Visual validation state of the select | `'error' \| 'none' \| 'success' \| 'warning'` | `'none'` | | `value` | `value` | The currently selected value; can be a string or array of strings in multi-select mode | `string \| string[]` | — | ### Methods | Method | Parameters | Returns | Description | | -------------- | --------------------------- | --------------- | ---------------------------------------------- | | `clear()` | — | `Promise` | Clears the selected value and resets the input | | `reset(value)` | `value: string \| string[]` | `Promise` | Resets the select to the supplied `value` | ### Events | Event | Description | | ---------- | ----------------------------------------------------------------------------------------------------------------------- | | `bqBlur` | Emitted when the Select input loses focus | | `bqClear` | Emitted when the selected value has been cleared | | `bqFocus` | Emitted when the Select input receives focus | | `bqInput` | Emitted when the input value changes while typing; detail is `{ value: string \| number \| string[] }` | | `bqSelect` | Emitted when the selected value changes; detail is `{ value: string \| number \| string[]; item: HTMLBqOptionElement }` | ### Slots | Slot | Description | | ------------- | --------------------------------------------------------------- | | *(default)* | The `bq-option` elements that make up the option list | | `label` | The label displayed above the input | | `prefix` | Content shown before the value text inside the control | | `tags` | Replaces the auto-generated tag list in multi-select mode | | `clear-icon` | Replaces the default clear icon inside the clear button | | `suffix` | Content shown after the value text; defaults to a chevron caret | | `helper-text` | Text shown below the input for guidance or validation messages | ### Shadow parts | Part | Description | | ---------------- | ---------------------------------------------------------- | | `base` | The component's root wrapper `
` | | `button` | The native `