;
};
`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
## 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.
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
Each option has an interactive row with a label and optional prefix, suffix, and checkbox controls.
| Part | Element | Description |
| - | - | - |
| **1** | Option row | Interactive surface that contains the option controls and content |
| **2** | Label | The main text content of the option |
| **3** | Prefix | Optional slot for an icon or element rendered before the label |
| **4** | Suffix | Optional slot for an icon or element rendered after the label |
| **5** | Checkbox | Optional selection control for checkbox options |
## 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.
### 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.
:host {
align-items: stretch !important;
flex-direction: column !important;
justify-content: flex-start !important;
}
User profileChange passwordClose session
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileChange passwordClose session
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqOption, BqOptionList } from "@beeq/react";
User profileChange passwordClose 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 profileChange passwordClose session
`,
})
export class DefaultOptionComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileChange passwordClose session
```
### 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](/components/select) manages checkbox, selected, and indeterminate states. `bq-option-list` alone defaults to a listbox and is not the parent for nested tree items.
body {
padding: var(--bq-spacing-l);
}
Frontend
2 levelsReactVue
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Frontend
2 levelsReactVue
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqOption, BqSelect } from "@beeq/react";
Frontend
2 levelsReactVue
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqOption, BqSelect } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqOption, BqSelect],
template: `
Frontend
2 levelsReactVue
`,
})
export class NestedOptionComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Frontend
2 levelsReactVue
```
### 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.
:host {
align-items: stretch !important;
flex-direction: column !important;
justify-content: flex-start !important;
}
User profileChange passwordClose session
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileChange passwordClose session
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqOption, BqOptionList } from "@beeq/react";
User profileChange passwordClose 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 profileChange passwordClose session
`,
})
export class OptionWithPrefixIconComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileChange passwordClose session
```
### With suffix icon
Use the `suffix` slot for a right-aligned secondary indicator. Common uses include link-out arrows, keyboard shortcuts, or status icons.
:host {
align-items: stretch !important;
flex-direction: column !important;
justify-content: flex-start !important;
}
User profileAdmin dashboardChange passwordClose session
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileAdmin dashboardChange passwordClose session
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqOption, BqOptionList } from "@beeq/react";
User profileAdmin dashboardChange passwordClose 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 profileAdmin dashboardChange passwordClose session
`,
})
export class OptionWithSuffixIconComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileAdmin dashboardChange passwordClose session
```
## Options
### Selected state
Set `selected` on the option that reflects the current active value. The component applies the brand accent styling automatically.
:host {
align-items: stretch !important;
flex-direction: column !important;
justify-content: flex-start !important;
}
User profileChange passwordClose session
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileChange passwordClose session
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqOption, BqOptionList } from "@beeq/react";
User profileChange passwordClose 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 profileChange passwordClose session
`,
})
export class SelectedOptionComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileChange passwordClose session
```
### 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](/components/select), set `multiple` and `enable-checkboxes` on Select instead. Select applies checkbox presentation to its options. Nested multiple Selects always render checkboxes.
:host {
align-items: stretch !important;
flex-direction: column !important;
justify-content: flex-start !important;
}
Email notifications
Product updates
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Email notifications
Product updates
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqOption, BqOptionList } from "@beeq/react";
Email notifications
Product updates
```
```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: `
Email notifications
Product updates
`,
})
export class CheckboxOptionComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Email notifications
Product updates
```
### 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.
:host {
align-items: stretch !important;
flex-direction: column !important;
justify-content: flex-start !important;
}
User profileAdmin dashboardChange passwordClose session
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileAdmin dashboardChange passwordClose session
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqOption, BqOptionList } from "@beeq/react";
User profileAdmin dashboardChange passwordClose 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 profileAdmin dashboardChange passwordClose session
`,
})
export class DisabledOptionComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileAdmin dashboardChange passwordClose session
```
### 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.
:host {
align-items: stretch !important;
flex-direction: column !important;
justify-content: flex-start !important;
}
User profileAdmin dashboardChange passwordClose session
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileAdmin dashboardChange passwordClose session
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqOption, BqOptionList } from "@beeq/react";
User profileAdmin dashboardChange passwordClose 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 profileAdmin dashboardChange passwordClose session
`,
})
export class HiddenOptionComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
User profileAdmin dashboardChange passwordClose session
```
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
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.
* Nested checkbox options expose `aria-checked` 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** — use `bq-option-list` for a standalone flat list, or `bq-select` for select options. Do 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. Avoid icon-only options; always include a visible text label.
* **Keyboard navigation** — for a nested Select, let the Select handle `ArrowUp`, `ArrowDown`, `ArrowRight`, and `ArrowLeft`. Do not intercept these keys in your own handlers.
## API reference
### Properties
| Property | Attribute | Description | Type | Default |
| - | - | - | - | - |
| `allSelectedLabel` | `all-selected-label` | Text shown beside the expand control when all selectable descendants are selected | `string` | `'All selected'` |
| `checkbox` | `checkbox` | If `true`, renders the option as a checkbox option | `boolean` | `false` |
| `disabled` | `disabled` | If true, the option is disabled | `boolean` | `false` |
| `displayValue` | `display-value` | Overrides the default displayed value of the option | `string` | — |
| `expanded` | `expanded` | If `true`, displays child options from the `options` slot | `boolean` | `false` |
| `hidden` | `hidden` | If true, the option is hidden | `boolean` | `false` |
| `indeterminate` | `indeterminate` | If `true`, the checkbox represents a partial nested selection | `boolean` | `false` |
| `selected` | `selected` | If true, the option is selected and active | `boolean` | `false` |
| `selectedCountLabel` | `selected-count-label` | Partial-selection summary. Use `{count}` for the selected descendant count | `string` | `'{count} selected'` |
| `showSelectionSummary` | `show-selection-summary` | If `true`, shows the nested selection summary beside the expand control | `boolean` | `true` |
| `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 or Space activates a focused option. Activation through its checkbox control emits `bqClick` instead | `CustomEvent` |
| `bqFocus` | Emitted when the option receives focus | `CustomEvent` |
### Slots
| Slot | Description |
| - | - |
| *(default)* | The label text content of the option |
| `expand-label` | Optional text inside the expand or collapse control |
| `options` | Nested option items shown when the parent is expanded |
| `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 option selection control |
| `item` | The interactive option row |
| `label` | The `` element containing the label text |
| `prefix` | The `` element wrapping the prefix slot content |
| `suffix` | The `` element wrapping the suffix slot content |
| `checkbox-base` | Base wrapper exported from the nested checkbox |
| `checkbox-control` | Control wrapper exported from the nested checkbox |
| `checkbox-input` | Native input exported from the nested checkbox |
| `checkbox-checkbox` | Checkbox indicator exported from the nested checkbox |
| `checkbox-label` | Label exported from the nested checkbox |
| `expand` | Expand or collapse button |
| `expand-button` | Native button exported from the expand control |
| `expand-label` | Label exported from the expand control |
| `selection-summary` | Nested selection summary beside the expand control |
| `options` | Container for nested options |
### CSS custom properties
| Variable | Description | Default |
| - | - | - |
| `--bq-option--background` | Option background color | `var(--bq-ui--primary)` |
| `--bq-option--font-size` | Option label font size | `var(--bq-font-size--m)` |
| `--bq-option--border-color` | Option border color | `transparent` |
| `--bq-option--border-style` | Option border style | `none` |
| `--bq-option--border-width` | Option border width | `0` |
| `--bq-option--border-radius` | Option border radius | `var(--bq-radius--s)` |
| `--bq-option--box-shadow` | Option box shadow | `none` |
| `--bq-option--gap-start` | Gap between prefix icon and label | `var(--bq-spacing-s)` |
| `--bq-option--gap-end` | Gap between label and suffix icon | `var(--bq-spacing-s)` |
| `--bq-option--paddingY` | Vertical padding | `var(--bq-spacing-xs)` |
| `--bq-option--padding-start` | Inline-start padding | `var(--bq-spacing-s)` |
| `--bq-option--padding-end` | Inline-end padding | `var(--bq-spacing-s)` |
Learn more about [styling with shadow parts](/guides/styles) and [CSS custom properties](/theming/global-css-variables).
## Resources
Explore option variants and states in Storybook
View the component source on GitHub
## Related topics
- [Option List](/components/option-list.md)
- [Option Group](/components/option-group.md)
- [Breadcrumb](/components/breadcrumb.md)
- [Status](/components/status.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
`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.
Each option has an interactive row with a label and optional prefix, suffix, and checkbox controls.
| Part | Element | Description |
| - | - | - |
| **1** | Option row | Interactive surface that contains the option controls and content |
| **2** | Label | The main text content of the option |
| **3** | Prefix | Optional slot for an icon or element rendered before the label |
| **4** | Suffix | Optional slot for an icon or element rendered after the label |
| **5** | Checkbox | Optional selection control for checkbox options |
## Design guidelines
### States