bq-option-group wraps a set of bq-option items under a shared label, creating a named section within a longer list. Use it to reduce cognitive load when a menu contains many choices that naturally fall into categories.
bq-option-group must be placed inside a bq-option-list. The group renders a role="group" container, which assistive technologies expect to find within a role="listbox" ancestor — provided by bq-option-list.When to use
Use option groups when
- A list contains many options that share a common category — grouping reduces scanning effort
- The menu mixes conceptually different types of choices that would be confusing in a flat list
- You want to communicate hierarchy or context within a dropdown or select component
Do not use option groups when
- The list has only a handful of options — adding group headers adds visual weight without benefit
- All options belong to the same category — a single unlabelled list communicates this more cleanly
- The groups would each contain only one option, which implies the grouping is artificial
Option Group patterns
Category grouping
Group options by domain category — for example, splitting a sports/food selection into named sections. The label names the category; the options beneath it list the choices.
Role or permission tier
In access-control menus, group options by permission level (Admin, Editor, Viewer) so users can see which actions belong to which role at a glance.
Recent vs. all
Separate a “Recently used” group from a full list of options. Users who revisit common choices find them faster without searching the entire list.
Anatomy
bq-option items.
| Part | Element | Description |
|---|---|---|
| 1 | Prefix | Optional slot rendered before the group label — typically a bq-icon |
| 2 | Label | The text that names the group, placed in the header-label slot |
| 3 | Suffix | Optional slot rendered after the group label — typically a bq-icon or badge |
| 4 | Group container | The div that holds all slotted option items |
Design guidelines
Label clarity
The group label exists to help users understand why these options are grouped together. Write it as a short noun phrase — a category name, not an instruction.Name the category
Use a noun or short noun phrase: “Sport”, “Food”, “Recent”, “Admin actions”. The label names the group, not the action.
Keep it short
The label is displayed in a constrained space and truncates on overflow. Aim for one to three words.
Nesting and depth
Option groups are flat by design — they do not support nesting. Each group sits at the same level inside
bq-option-list. If you find yourself needing nested groups, reconsider the information architecture: a deeper hierarchy usually belongs in a separate navigation component rather than a dropdown.Prefix and suffix icons
Use theheader-prefix slot to place a category icon next to the label. This helps users identify the group at a glance in long lists. Use the header-suffix slot sparingly — a count badge or status indicator can add value, but too many suffix elements make the header feel cluttered.
Usage
Basic grouping
Two groups of options inside a singlebq-option-list. Each group carries a header-label that names the category.
Options
With prefix icon on the group header
Add abq-icon in the header-prefix slot to give the group label a visual category marker. This is most useful when the list is dense and users need to scan groups without reading every label word-for-word.
With suffix on the group header
Use theheader-suffix slot to place a count badge, status chip, or secondary icon after the label. The suffix is right-aligned and does not interfere with the label truncation.
Best practices
DoAlways provide content in the
header-label slot so screen readers and sighted users both know what the group represents.Don’tRender a group without a label — an unnamed group header creates visual ambiguity and an unnamed
role="group" gives screen readers nothing useful to announce.DoInclude at least two options in each group — a group containing a single item implies the grouping is arbitrary.
Don’tCreate groups where every group contains only one option. If no meaningful category exists, use a flat
bq-option-list instead.DoKeep group labels short — one to three words. The label is displayed in a constrained header row and truncates when it overflows.
Don’tWrite full sentences as group labels. Long text truncates silently and makes the header unreadable in narrow containers.
DoUse groups consistently — if one group has a prefix icon, give all groups a prefix icon so the header row stays visually aligned.
Don’tMix groups with and without prefix icons in the same list. The inconsistent indentation makes the list harder to scan.
Accessibility
bq-option-group renders a role="group" container div that holds the slotted option items. The internal container carries aria-label="Options" as a hardcoded fallback — this is not configurable via a prop. Screen readers use the text in the header-label slot to identify the group; the hardcoded aria-label is only a structural safety net for the container element itself.
As a developer, you are responsible for:
- Always providing
header-labelcontent — the text in this slot is what sighted users and screen reader users rely on to understand what the group is about. Without it, the group boundary is invisible to assistive technologies. - Placing the component inside
bq-option-list—bq-option-groupprovidesrole="group", which must be a descendant ofrole="listbox"(supplied bybq-option-list). Rendering option groups outside this context breaks the expected ARIA tree structure. - Keeping groups non-empty — a group with no options creates an orphaned header with no associated list items, which confuses both sighted users and screen readers.
API reference
Properties
bq-option-group has no configurable properties. Its behaviour is entirely controlled through slots.
Slots
| Slot | Description |
|---|---|
| (default) | The bq-option items belonging to this group |
header-label | The text label that names the group |
header-prefix | Content rendered before the label — typically a bq-icon |
header-suffix | Content rendered after the label — typically a bq-icon or badge |
Shadow parts
| Part | Description |
|---|---|
label | The <legend> element that acts as the group header container |
prefix | The <span> wrapping the header-prefix slot content |
suffix | The <span> wrapping the header-suffix slot content |
group | The <div> that holds the slotted option items |
CSS custom properties
Resources
Interactive playground
Explore option group variants and states in Storybook
Source code
View the component source on GitHub