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-buttonorbq-checkboxinstead - 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-listcontext
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.
Anatomy
| 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.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.Prefix only
The most common pattern. One icon on the left anchors the visual rhythm of the list and speeds up scanning.
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.
Usage
Default
A simple list of options inside abq-option-list. Each option carries a value attribute used by the parent to identify which item the user selected.
With prefix icon
Add abq-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 thesuffix slot for a right-aligned secondary indicator. Common uses include link-out arrows, keyboard shortcuts, or status icons.
Options
Selected state
Setselected on the option that reflects the current active value. The component applies the brand accent styling automatically.
Disabled state
Setdisabled 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
Sethidden 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.
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
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 whenselectedistrue, communicating the active choice to screen readers.aria-disabledis always present on the host. It is set to"true"whendisabledorhiddenistrue, and to"false"otherwise, ensuring assistive technologies always have the correct interactive state.aria-hidden="true"is set whenhiddenistrue, removing the item from the accessibility tree entirely.
- Placing options inside
bq-option-list— therole="option"on each item requires arole="listbox"ancestor, whichbq-option-listprovides. 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-optionlistens forEnterkeydown and emitsbqEnter. The parentbq-option-listhandlesArrowUp/ArrowDownfocus 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<HTMLBqOptionElement> |
bqClick | Emitted when the option is clicked | CustomEvent<HTMLBqOptionElement> |
bqEnter | Emitted when Enter is pressed while the option is focused | CustomEvent<HTMLBqOptionElement> |
bqFocus | Emitted when the option receives focus | CustomEvent<HTMLBqOptionElement> |
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 <button> wrapper of the option |
label | The <span> element containing the label text |
prefix | The <span> element wrapping the prefix slot content |
suffix | The <span> element wrapping the suffix slot content |
CSS custom properties
Resources
Interactive playground
Explore option variants and states in Storybook
Source code
View the component source on GitHub