Skip to main content
BEEQ Select component overview

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 instead
  • The choices are binary (yes / no, on / off) — use a Checkbox or toggle instead

​
Patterns

Single select

Single Select allows the user to pick one option from a menu.

Multiple select

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

Select component anatomy

The select is composed of a label, an input field, a dropdown panel, and optional status indicators.

​
Design guidelines

​
Single vs. multiple selection

​
Validation states

​
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.

​
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.

​
Initial value

Set an initial value for the select component to preselect an option, providing a streamlined user experience and minimizing manual input.

​
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.

​
Disabled

Employ the disabled attribute to restrict user interaction with the select component temporarily, useful for scenarios where certain options are unavailable.

​
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.

​
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.

​
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.

​
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.

​
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.

​
Label with “Info Tooltip”

Enhance user understanding by incorporating a bq-tooltip alongside the label, offering additional information or clarification about the select.

​
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.

​
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.

​
With no Helper Text

Select this variant when you don’t need additional helper text, giving users a straightforward and uncluttered experience.

​
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.

​
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.

​
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.

​
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.

​
Best practices

DoAlways populate the label slot so the select has an accessible name visible to all users, not just those relying on assistive technology.

Don’tLeave 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.

DoWrite 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’tUse 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.

DoUse 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’tApply validation-status="error" without a helper text message — a red border alone does not tell users what is wrong or how to correct it.

DoProvide meaningful option labels that describe the value clearly — e.g., “Europe” instead of “EU”, “Pro plan ($49/mo)” instead of “pro”.

Don’tUse 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 <input> 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 <form> 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

​
Methods

​
Events

​
Slots

​
Shadow parts

​
CSS custom properties

Learn more about styling with shadow parts and CSS custom properties.

​
Resources

Interactive playground

Explore Select variants and states in Storybook

Source code

View the component source on GitHub