> ## 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. # Radio > Radio buttons let users select exactly one option from a set of mutually exclusive choices. 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}
}
; }; export const CardTile = ({title, href, imageLightSrc, imageDarkSrc, children, enableImgZoom}) => { if (!href) { return
{imageLightSrc && {title}} {imageDarkSrc && {title}} {title &&

{title}

}
{children}
; } return {imageLightSrc && {title}} {imageDarkSrc && {title}} {title &&

{title}

}
{children}
; }; BEEQ Radio component overview BEEQ Radio component overview Radio buttons present a list of options where only one can be active at a time. When a user selects a new option, the previous selection is cleared automatically. Use them inside a `bq-radio-group` to connect the options and manage state. Always wrap `bq-radio` elements inside a `bq-radio-group`. The group manages selection state, keyboard navigation, form association, and accessibility — an isolated `bq-radio` cannot do this on its own. ## When to use Use radio buttons when * Users must select exactly one option from a short list (2–7 items) * All available options need to be visible so users can compare them before choosing * The choice persists until the user actively changes it * An option needs to trigger a visible change in the surrounding form or UI Do not use radio buttons when * Multiple selections are allowed — use [Checkbox](/components/checkbox) instead * The list is long and searchable — use a [Dropdown](/components/dropdown) instead * A binary on/off toggle is all that is needed — a toggle or checkbox is clearer * The options are so numerous that displaying them all creates visual noise ## Patterns By default, a radio button remains unchecked, implying it remains inactive until selected. Once a radio button is selected, it becomes active, signifying its chosen status. ## Anatomy BEEQ Radio component anatomy BEEQ Radio component anatomy A radio button consists of a circular icon and a text label. The icon changes appearance depending on whether the option is selected or unselected. | Part | Element | Description | | ----- | ----------------- | ---------------------------------------------------------------------------------- | | **1** | Icon (selected) | The filled circular control shown when the radio is the active choice in the group | | **2** | Label text | The `` that holds the option text and extends the clickable area | | **3** | Icon (unselected) | The empty circular control shown when the radio is not the active choice | ## Design guidelines Stack options vertically when the labels are longer than a few words. Vertical lists are easier to scan and less prone to accidental selection. Arrange options in a row when the labels are short (one or two words) and the total number of choices is small. Use this for compact filters or sort controls. Enable `fieldset` on the group to render a visible border and legend around the options. Use this when the radio group is one of several form sections that need visual separation. Enable `background-on-hover` to show a filled background on the label row when the user hovers. Use this to increase the perceived click area in spacious layouts. ## Usage ### Default Wrap `bq-radio` elements inside a `bq-radio-group`. Set a matching `value` on the group to pre-select one option. The group handles all state synchronization. Label Radio option 1 Radio option 2 Radio option 3 `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Label Radio option 1 Radio option 2 Radio option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqRadio, BqRadioGroup } from "@beeq/react"; Label Radio option 1 Radio option 2 Radio option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqRadio, BqRadioGroup } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqRadio, BqRadioGroup], template: ` Label Radio option 1 Radio option 2 Radio option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### Disabled Set `disabled` on the group to prevent all interaction. You can also disable individual `bq-radio` elements when only specific options are unavailable. :host { gap: var(--bq-spacing-l) !important; } Label Radio option 1 Radio option 2 Radio option 3 Label Radio option 1 Radio option 2 Radio option 3 `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Label Radio option 1 Radio option 2 Radio option 3 Label Radio option 1 Radio option 2 Radio option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqRadio, BqRadioGroup } from "@beeq/react"; {/* Fully disabled group */} Label Radio option 1 Radio option 2 Radio option 3 {/* Individual radio disabled */} Label Radio option 1 Radio option 2 Radio option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqRadio, BqRadioGroup } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqRadio, BqRadioGroup], template: ` Label Radio option 1 Radio option 2 Radio option 3 Label Radio option 1 Radio option 2 Radio option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Horizontal Use `orientation="horizontal"` to arrange options side by side. Best for short labels and a small number of choices where vertical space is limited. Label Radio option 1 Radio option 2 Radio option 3 `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Label Radio option 1 Radio option 2 Radio option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqRadio, BqRadioGroup } from "@beeq/react"; Label Radio option 1 Radio option 2 Radio option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqRadio, BqRadioGroup } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqRadio, BqRadioGroup], template: ` Label Radio option 1 Radio option 2 Radio option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Fieldset Add the `fieldset` attribute to render a visible border and legend around the group. Use this when the radio group is one of several distinct sections in a form that need visual separation. Label Radio option 1 Radio option 2 Radio option 3 `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Label Radio option 1 Radio option 2 Radio option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqRadio, BqRadioGroup } from "@beeq/react"; Label Radio option 1 Radio option 2 Radio option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqRadio, BqRadioGroup } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqRadio, BqRadioGroup], template: ` Label Radio option 1 Radio option 2 Radio option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Background on hover Set `background-on-hover` on the group (or on individual `bq-radio` elements) to show a filled highlight on the label row when the user hovers. This increases the perceived click area in spacious layouts. Label Radio option 1 Radio option 2 Radio option 3 `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Label Radio option 1 Radio option 2 Radio option 3 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqRadio, BqRadioGroup } from "@beeq/react"; Label Radio option 1 Radio option 2 Radio option 3 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqRadio, BqRadioGroup } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqRadio, BqRadioGroup], template: ` Label Radio option 1 Radio option 2 Radio option 3 ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Form integration `bq-radio-group` submits the selected radio value with the form. Use `required` and `required-validation-message` on the group when users must choose one option before submission. body { padding: var(--bq-spacing-l); } .radio-form { display: grid; gap: var(--bq-spacing-m); } .radio-form__actions { display: flex; gap: var(--bq-spacing-s); justify-content: flex-end; } .radio-form__output { margin: 0; padding: var(--bq-spacing-s); border: var(--bq-stroke-s) solid var(--bq-stroke--tertiary); border-radius: var(--bq-radius--s); background: var(--bq-ui--secondary); color: var(--bq-text--primary); white-space: pre-wrap; } bq-radio-group::part(base) { border-color: var(--bq-stroke--primary); border-radius: var(--bq-radius--m); border-width: var(--bq-stroke-s); }
Preferred contact method Email Phone Chat
Reset Submit 
{}
`} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Preferred contact method Email Phone Chat Reset Submit 
{}
``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { useState } from "react"; import { BqButton, BqRadio, BqRadioGroup } from "@beeq/react"; export default function RadioForm() { const [data, setData] = useState("{}"); return (
setData("{}")} onSubmit={(event) => { event.preventDefault(); setData(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget).entries()), null, 2)); }} > Preferred contact method Email Phone Chat Reset Submit 
{data}
); } ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqRadio, BqRadioGroup } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqRadio, BqRadioGroup], template: `
Preferred contact method Email Phone Chat Reset Submit 
{{ data }}
`, }) export class RadioFormComponent { data = "{}"; handleSubmit(event: SubmitEvent): void { event.preventDefault(); this.data = JSON.stringify(Object.fromEntries(new FormData(event.target as HTMLFormElement).entries()), null, 2); } } ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Always provide a group label via the `label` slot on `bq-radio-group` so screen readers announce the question or field name when focus enters the group. Don't Leave the `label` slot empty — users relying on assistive technology will not know what the radio group is asking. Do Pre-select a sensible default by setting `value` on the group so the form always has a valid starting state and users understand which option is active on first view. Don't Leave all options unselected when one choice is always required — an empty radio group can cause confusing form validation errors on submit. Do Write option labels as nouns or short phrases that clearly describe each choice so users can compare them at a glance. Don't Use vague labels like "Option 1" or "Yes/No" when more descriptive text would make the choice immediately understandable without additional context. Do Use `disabled` on the entire group when the choice is unavailable in the current context, and explain why it is locked via nearby helper text. Don't Disable individual radio options without a visible explanation — users will not know whether the option is temporarily locked or permanently unavailable. ## Accessibility * **Built in:** `bq-radio-group` renders as a `
` (when `fieldset` is set) with a `` linked to the `label` slot, giving screen readers a proper group label for the set. * **Built in:** each `bq-radio` native `` carries `aria-checked`, `aria-disabled`, and `aria-labelledby` pointing to its visible label element. * **Built in:** arrow-key navigation is handled by the group — `ArrowDown` / `ArrowRight` move to the next radio, `ArrowUp` / `ArrowLeft` move to the previous one, wrapping at the ends. This matches the ARIA radio group keyboard pattern. * **Built in:** only one radio in the group receives `tabindex="0"` at a time (the selected or first enabled option), keeping the tab stop count low. * **Your responsibility:** always populate the `label` slot on `bq-radio-group` — the `aria-labelledby` reference on the group requires a visible label element to give the fieldset an accessible name. * **Your responsibility:** provide meaningful text inside each `bq-radio` slot — the `aria-labelledby` on the native input points to the label span, so empty or icon-only labels are not announced. * **Your responsibility:** when you disable the group, add visible helper text nearby explaining why the options are unavailable. ## API reference ### `bq-radio` properties | Property | Attribute | Description | Type | Default | | ------------------- | --------------------- | ------------------------------------------------------------------------ | --------- | ------- | | `backgroundOnHover` | `background-on-hover` | If `true`, the radio displays a background highlight on hover | `boolean` | `false` | | `checked` | `checked` | If `true`, the radio input is checked | `boolean` | `false` | | `disabled` | `disabled` | If `true`, the radio input is disabled | `boolean` | `false` | | `formId` | `form-id` | The ID of the `
` element the radio is associated with | `string` | — | | `name` | `name` | Name of the form control, submitted as part of a name/value pair | `string` | — | | `required` | `required` | If `true`, the user must select a value before the form can be submitted | `boolean` | `false` | | `value` | `value` | The string value of the radio, submitted with the form | `string` | — | ### `bq-radio-group` properties | Property | Attribute | Description | Type | Default | | --------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------- | ------------ | | `backgroundOnHover` | `background-on-hover` | If `true`, all radios in the group show a background on hover | `boolean` | `false` | | `debounceTime` | `debounce-time` | Delay in milliseconds before `bqChange` fires after a value change | `number` | `0` | | `disabled` | `disabled` | If `true`, all radio inputs in the group are disabled | `boolean` | `false` | | `fieldset` | `fieldset` | If `true`, the group renders a visible fieldset border with a legend | `boolean` | `false` | | `name` | `name` | Name of the form control, submitted with the selected radio's value | `string` | — | | `orientation` | `orientation` | Layout direction of the radio inputs | `'horizontal' \| 'vertical'` | `'vertical'` | | `required` | `required` | If `true`, the radio group is required | `boolean` | `false` | | `requiredValidationMessage` | `required-validation-message` | Native form validation message shown when the group is required and no option is selected | `string` | — | | `value` | `value` | The value of the currently selected radio | `string` | — | ### `bq-radio` methods | Method | Description | | ------------------ | ---------------------------------------------------------------------------- | | `vClick()` | Simulates a click on the native `` — use instead of `element.click()` | | `vFocus()` | Sets focus on the native `` — use instead of `element.focus()` | | `vBlur()` | Removes focus from the native `` — use instead of `element.blur()` | | `getNativeInput()` | Returns the native `` HTML element used under the hood | ### `bq-radio` events | Event | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------- | | `bqClick` | Emitted when the radio is clicked; detail is `{ value: string; target: HTMLBqRadioElement }` | | `bqFocus` | Emitted when the radio receives focus | | `bqBlur` | Emitted when the radio loses focus | | `bqKeyDown` | Emitted when a key is pressed while the radio is focused; detail is `{ key: string; target: HTMLBqRadioElement }` | ### `bq-radio-group` events | Event | Description | | ---------- | -------------------------------------------------------------------------------------------------- | | `bqChange` | Emitted when the selected radio changes; detail is `{ value: string; target: HTMLBqRadioElement }` | | `bqBlur` | Emitted when focus leaves the entire group | ### `bq-radio` slots | Slot | Description | | ----------- | ------------------------------------------- | | *(default)* | The visible label text for the radio option | ### `bq-radio-group` slots | Slot | Description | | ----------- | ---------------------------------------------------------------- | | *(default)* | The `bq-radio` elements that make up the group | | `label` | The group's label text, rendered as a legend inside the fieldset | ### `bq-radio` shadow parts | Part | Description | | ------- | ------------------------------------------------------------------ | | `base` | The `