Skip to main content
BEEQ Option component overviewBEEQ Option component overview

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.
Place standalone options in bq-option-list, or use them as direct children of bq-select. A nested bq-select manages the tree semantics, selection state, and checkboxes for its options.

​
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 not be managed by bq-option-list, bq-select, or another component that provides list semantics
Choose bq-option for a single selectable item, bq-option-group to put related options under a shared label, and bq-option-list as the listbox container that holds the options and groups and emits bqSelect.

​
Option patterns

Label only

The simplest form — a text label with no icon. Use for compact menus where space is limited and the labels are self-explanatory.

Prefix icon + label

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.

Label + suffix icon

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.

Nested parent

A parent option contains related child options. Use this pattern only inside a multiple bq-select, where the Select manages cascading, mixed state, and keyboard tree navigation.

​
Anatomy

BEEQ Option component anatomyBEEQ Option component anatomy

Option component anatomy

Each option has an interactive row with a label and optional prefix, suffix, and checkbox controls.

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

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

Prefix only

The most common pattern. One icon on the left anchors the visual rhythm of the list and speeds up scanning.
2

Suffix only

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

Prefix and suffix

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.

​
Nested parent options

Use expanded and the options slot to define a branch. Inside a nested bq-select, do not manage selected, indeterminate, or checkbox on the parent yourself: Select keeps those states in sync with the canonical value. The parent can show a label beside its expand control through expand-label. show-selection-summary controls the generated summary; customise its complete and partial text with all-selected-label and selected-count-label. The latter replaces {count} with the number of selected selectable descendants.

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

​
Nested parent

Use expanded on the parent and place child options in its options slot. Give every option in the branch a unique value, and use a multiple bq-select so the options have a tree container and managed keyboard navigation.
A nested multiple Select manages checkbox, selected, and indeterminate states. bq-option-list alone defaults to a listbox and is not the parent for nested tree items.

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

​
With suffix icon

Use the suffix slot for a right-aligned secondary indicator. Common uses include link-out arrows, keyboard shortcuts, or status icons.

​
Options

​
Selected state

Set selected on the option that reflects the current active value. The component applies the brand accent styling automatically.

​
Checkbox option

Set checkbox to render a checkbox inside a standalone option list. Use selected to reflect an initial checked state.
Inside a flat Select, set multiple and enable-checkboxes on Select instead. Select applies checkbox presentation to its options. Nested multiple Selects always render checkboxes.

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

​
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.
To organize options into labeled sections, wrap bq-option elements in bq-option-group and place the groups inside a bq-option-list. The Option Group page has full code examples including header prefix and suffix customization.

​
Best practices

DoAlways provide a value attribute on each option so the parent component can identify which item was selected.
Don’tOmit the value attribute. Without it, the parent bq-option-list or select-like component cannot distinguish which option the user chose.
DoUse disabled for options that are temporarily unavailable in the current context — keeping them visible signals that the feature exists.
Don’tUse 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.
DoKeep option labels short and descriptive — one to four words that clearly identify the action or destination.
Don’tWrite long sentences as option labels. Long labels break the visual rhythm of the list and make scanning harder.
DoUse consistent icon placement across all options in the same list — either all with prefix icons or all without.
Don’tMix options with icons and options without icons in the same list — the uneven spacing makes the list look misaligned.

​
Accessibility

For flat options, bq-option sets role="option" and exposes aria-selected. In a nested bq-select, the Select switches the option to role="treeitem" and manages the relationship with its tree container.
  • aria-selected communicates the selected state for a flat option.
  • Checkbox options inside a bq-select (nested, or flat with enable-checkboxes) expose aria-checked instead of aria-selected, as "true", "false", or "mixed" for a partial branch.
  • Nested parents expose aria-expanded, and their child container uses role="group" while it is visible.
  • aria-disabled is always present on the host. It is "true" when disabled or hidden is true.
  • aria-hidden="true" removes a hidden option from the accessibility tree.
As a developer, you are responsible for:
  • Choosing the right parent — you must use bq-option-list for a standalone flat list, or bq-select for select options, and must not put options in an arbitrary container.
  • Providing meaningful labels — the text inside the default slot is read by screen readers as the option’s accessible name. Options must include a visible text label and must not be icon-only.
  • Keyboard navigation — for a nested Select, the Select must handle ArrowUp, ArrowDown, ArrowRight, and ArrowLeft. You must not intercept these keys in your own handlers.

​
Keyboard interaction

Keys apply to the focused option. Disabled and hidden options are not focusable.

​
Rules

​
API reference

​
Properties

​
Invalid combinations

​
Events

​
Slots

​
Shadow parts

​
CSS custom properties

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

​
Resources

Interactive playground

Explore option variants and states in Storybook

Source code

View the component source on GitHub