> ## Documentation Index > Fetch the complete documentation index at: https://www.beeq.design/llms.txt > Use this file to discover all available pages before exploring further. # Option Group > Option Group is a labelled container that organizes related options into named sections inside a list or dropdown. export const CodeLivePreview = ({code, children, height, removePadding = false, mode = 'shadow'}) => { const previewRef = useRef(null); const BEEQ_ESM_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.esm.js'; const BEEQ_CSS_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.css'; const BEEQ_ICONS_URL = 'https://esm.sh/@beeq/core/dist/beeq/svg'; const ensureParentBeeqRuntime = () => { if (document.querySelector('script[data-beeq-parent-runtime]')) return; const script = document.createElement('script'); script.type = 'module'; script.src = BEEQ_ESM_URL; script.dataset.beeqParentRuntime = BEEQ_ICONS_URL; document.head.appendChild(script); }; const executeSnippetScripts = (root, runtimeWindow, previewRootArg, skipAttr) => { root.querySelectorAll('script').forEach(oldScript => { if (skipAttr && oldScript.hasAttribute(skipAttr)) return; if (oldScript.src) { const newScript = runtimeWindow.document.createElement('script'); newScript.src = oldScript.src; oldScript.replaceWith(newScript); return; } runtimeWindow.Function('previewRoot', oldScript.textContent || '')(previewRootArg); oldScript.remove(); }); }; const syncIframeMode = iframeDoc => { const root = document.documentElement; const explicitMode = root.getAttribute('bq-mode'); const isDark = root.classList.contains('dark'); const resolvedMode = explicitMode || (isDark ? 'dark' : 'light'); iframeDoc.documentElement.setAttribute('bq-mode', resolvedMode); iframeDoc.body.setAttribute('bq-mode', resolvedMode); }; useEffect(() => { if (mode === 'shadow') ensureParentBeeqRuntime(); }, [mode]); useEffect(() => { const container = previewRef.current; if (!container) return; if (removePadding) container.style.padding = '0'; container.innerHTML = ''; if (mode === 'iframe') { const iframe = document.createElement('iframe'); iframe.className = 'preview-iframe'; iframe.style.width = '100%'; iframe.style.border = '0'; iframe.style.display = 'block'; iframe.style.minHeight = height ?? '0px'; iframe.setAttribute('title', 'Live code preview'); iframe.setAttribute('loading', 'lazy'); iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin'); container.appendChild(iframe); const iframeDoc = iframe.contentDocument; const iframeWin = iframe.contentWindow; if (!iframeDoc || !iframeWin) return; iframeDoc.open(); iframeDoc.write(['', '', '', ' ', ' ', ' ', ` `, ` `, '', '', code, '', ''].join('\n')); iframeDoc.close(); syncIframeMode(iframeDoc); const modeObserver = new MutationObserver(() => syncIframeMode(iframeDoc)); modeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'bq-mode'] }); executeSnippetScripts(iframeDoc, iframeWin, iframeDoc, 'data-beeq-iframe-runtime'); return () => modeObserver.disconnect(); } const shadowRoot = container.shadowRoot ?? container.attachShadow({ mode: 'open' }); if (!shadowRoot.adoptedStyleSheets.length) { const fixSheet = new CSSStyleSheet(); fixSheet.replaceSync(` bq-dropdown::part(panel), bq-panel::part(panel), bq-select::part(panel), bq-date-picker::part(panel) { z-index: 9999; } bq-tooltip::part(panel) { position: absolute; } `); shadowRoot.adoptedStyleSheets = [fixSheet]; } shadowRoot.innerHTML = [``, code].join(''); executeSnippetScripts(shadowRoot, window, shadowRoot); return undefined; }, [code, mode, height]); return
{}
{} {children &&
{children}
}
; }; BEEQ Option Group component overview BEEQ Option Group component overview `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 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. 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. 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 BEEQ Option Group component anatomy BEEQ Option Group component anatomy Each option group has a header row containing an optional prefix, the required label text, and an optional suffix. Below the header sits the container holding the slotted `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. Use a noun or short noun phrase: "Sport", "Food", "Recent", "Admin actions". The label names the group, not the action. The label is displayed in a constrained space and truncates on overflow. Aim for one to three words. Apply title case or sentence case consistently across all groups in the same list. Mixing styles creates visual noise. ### 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 the `header-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 single `bq-option-list`. Each group carries a `header-label` that names the category. Sport Running Hiking Biking Food Pizza Hamburger Cookie `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Sport Running Hiking Biking Food Pizza Hamburger Cookie ``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqOptionGroup, BqOptionList } from "@beeq/react"; Sport Running Hiking Biking Food Pizza Hamburger Cookie ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqOptionGroup, BqOptionList } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqOptionGroup, BqOptionList], template: ` Sport Running Hiking Biking Food Pizza Hamburger Cookie `, }) export class BasicOptionGroupComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### With prefix icon on the group header Add a `bq-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. Sport Running Hiking Biking Food Pizza Hamburger Cookie `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Sport Running Hiking Biking Food Pizza Hamburger Cookie ``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqOption, BqOptionGroup, BqOptionList } from "@beeq/react"; Sport Running Hiking Biking Food Pizza Hamburger Cookie ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqOption, BqOptionGroup, BqOptionList } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqOption, BqOptionGroup, BqOptionList], template: ` Sport Running Hiking Biking Food Pizza Hamburger Cookie `, }) export class OptionGroupWithPrefixIconComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### With suffix on the group header Use the `header-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. Sport 3 Running Hiking Biking Food 3 Pizza Hamburger Cookie `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Sport 3 Running Hiking Biking Food 3 Pizza Hamburger Cookie ``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqBadge, BqIcon, BqOption, BqOptionGroup, BqOptionList } from "@beeq/react"; Sport 3 Running Hiking Biking Food 3 Pizza Hamburger Cookie ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqBadge, BqIcon, BqOption, BqOptionGroup, BqOptionList } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqBadge, BqIcon, BqOption, BqOptionGroup, BqOptionList], template: ` Sport 3 Running Hiking Biking Food 3 Pizza Hamburger Cookie `, }) export class OptionGroupWithSuffixBadgeComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Always provide content in the `header-label` slot so screen readers and sighted users both know what the group represents. Don't Render a group without a label — an unnamed group header creates visual ambiguity and an unnamed `role="group"` gives screen readers nothing useful to announce. Do Include at least two options in each group — a group containing a single item implies the grouping is arbitrary. Don't Create groups where every group contains only one option. If no meaningful category exists, use a flat `bq-option-list` instead. Do Keep group labels short — one to three words. The label is displayed in a constrained header row and truncates when it overflows. Don't Write full sentences as group labels. Long text truncates silently and makes the header unreadable in narrow containers. Do Use groups consistently — if one group has a prefix icon, give all groups a prefix icon so the header row stays visually aligned. Don't Mix 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-label` content** — 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-group` provides `role="group"`, which must be a descendant of `role="listbox"` (supplied by `bq-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 `` element that acts as the group header container | | `prefix` | The `` wrapping the `header-prefix` slot content | | `suffix` | The `` wrapping the `header-suffix` slot content | | `group` | The `
` that holds the slotted option items | ### CSS custom properties | Variable | Description | Default | | --------------------------------------------- | -------------------------------------------------------- | ------------------------------------- | | `--bq-option-group--background` | Group background color | `var(--bq-ui--primary)` | | `--bq-option-group--font-size` | Group label font size | `var(--bq-font-size--s)` | | `--bq-option-group--line-height` | Group label line height | `var(--bq-font-line-height--regular)` | | `--bq-option-group--label-padding-start` | Inline-start padding of the group header | `var(--bq-spacing-s)` | | `--bq-option-group--label-padding-end` | Inline-end padding of the group header | `var(--bq-spacing-s)` | | `--bq-option-group--label-paddingY` | Block padding of the group header | `var(--bq-spacing-xs)` | | `--bq-option-group--label-text-padding-start` | Inline-start padding of the label text within the header | `var(--bq-spacing-s)` | | `--bq-option-group--label-text-padding-end` | Inline-end padding of the label text within the header | `var(--bq-spacing-s)` | | `--bq-option-group--container-padding-start` | Inline-start padding of the options container | `var(--bq-spacing-xxl)` | Learn more about [styling with shadow parts](/guides/styles) and [CSS custom properties](/theming/global-css-variables). ## Resources Explore option group variants and states in Storybook View the component source on GitHub