Radio

BEEQ Radio component overview — 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 instead
The list is long and searchable — use a 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

Choose bq-checkbox instead of bq-radio-group when users can select several options, bq-switch when the choice is a single on/off setting that applies immediately, bq-select when the list is too long to show every option in a form, and bq-dropdown when the options trigger actions instead of setting a form value.

Patterns

Default

By default, a radio button remains unchecked, implying it remains inactive until selected.

Selected

Once a radio button is selected, it becomes active, signifying its chosen status.

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 `<span>` 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

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.

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.

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. Allowed orientation values: vertical (default), horizontal. Any other value falls back to vertical.

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.

Background on hover

Set background-on-hover on the group to show a filled highlight on every label row when the user hovers. Inside a group, bq-radio-group overrides the value set on individual bq-radio elements. This increases the perceived click area in spacious layouts.

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.

Best practices

DoAlways 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’tLeave the label slot empty — users relying on assistive technology will not know what the radio group is asking.

DoPre-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’tLeave all options unselected when one choice is always required — an empty radio group can cause confusing form validation errors on submit.

DoWrite option labels as nouns or short phrases that clearly describe each choice so users can compare them at a glance.

Don’tUse vague labels like “Option 1” or “Yes/No” when more descriptive text would make the choice immediately understandable without additional context.

DoUse 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’tDisable 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 always renders a <fieldset> with a <legend> that holds the label slot. The fieldset property only adds the visible border.
Built in: each bq-radio native <input type="radio"> carries aria-checked, aria-disabled, and aria-labelledby pointing to its visible label element.
Built in: arrow keys focus and select the adjacent enabled radio, skip disabled radios and wrap at the ends. All four arrow keys work in both orientations; orientation controls layout only.
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: you must populate the label slot on bq-radio-group with meaningful group text.
Your responsibility: you must 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, you should add visible helper text nearby explaining why the options are unavailable.

Keyboard interaction

Key	Context	Action
`Tab`	Focus outside the group	Moves focus into the group, to the selected radio or the first enabled radio
`Tab`	Focus on a radio in the group	Moves focus out of the group to the next focusable element
`Shift` + `Tab`	Focus on a radio in the group	Moves focus out of the group to the previous focusable element
`ArrowDown`	Radio focused	Focuses and selects the next enabled radio; wraps from the last to the first
`ArrowRight`	Radio focused	Focuses and selects the next enabled radio; wraps from the last to the first
`ArrowUp`	Radio focused	Focuses and selects the previous enabled radio; wraps from the first to the last
`ArrowLeft`	Radio focused	Focuses and selects the previous enabled radio; wraps from the first to the last
`Space`	Unselected radio focused	Selects the focused radio (native `<input type="radio">` behavior)

All four arrow keys work in both orientations. A disabled group has no tab stop.

Rules

Rule	Strength	Verified by
Wrap every `bq-radio` in a `bq-radio-group`	MUST	manual: inspect the parent of every radio in the DOM
Fill the `label` slot of the group with meaningful text	MUST	manual: read the group label before its choices
Provide meaningful text in each `bq-radio` slot	MUST	manual: read each choice without relying on its position
Set `name` on the group so the selected value submits with the form	MUST	automated: `bq-radio-group.e2e.tsx` checks `FormData`
Select an option before submitting a required group	MUST	automated: `bq-radio-group.e2e.tsx` checks `form.checkValidity()`
Set `required-validation-message` on a required group	SHOULD	manual: inspect the required-group validation message
Pre-select a default with `value` when one choice is always required	SHOULD	manual: review the selected default against the question
Explain nearby why a group or option is disabled	SHOULD	manual: inspect nearby text for disabled choices

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 `<form>` 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`	—
`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. With `0`, `bqChange` is emitted synchronously	`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`	—

Invalid combinations

Combination	Strength	Result
`name` or `required` on a `bq-radio` inside a `bq-radio-group`	SHOULD NOT	The group overwrites both with its own `name` and `required` values
`required-validation-message` without `required` on the group	SHOULD NOT	The message is never used because the group is always valid
`debounce-time` below `0`	SHOULD NOT	The group clamps the value to `0`

`bq-radio` methods

Method	Description
`vClick()`	Simulates a click on the native `<input>` — use instead of `element.click()`
`vFocus()`	Sets focus on the native `<input>` — use instead of `element.focus()`
`vBlur()`	Removes focus from the native `<input>` — use instead of `element.blur()`
`getNativeInput()`	Returns the native `<input>` 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 `<label>` wrapper that contains the control and the label text
`input`	The native `<input type="radio">` element
`radio`	The `<div>` that renders the visible circular ring
`label`	The `<span>` that holds the option text content

`bq-radio-group` shadow parts

Part	Description
`base`	The `<fieldset>` wrapper that contains the label and all radio inputs
`label`	The `<legend>` that holds the group label slot content
`group`	The `<div>` that lays out the radio inputs

CSS custom properties

Hide CSS variables

Variable	Description	Default
`--bq-radio--background-color`	Background color of the radio control	`var(--bq-ui--primary)`
`--bq-radio--border-color`	Border color of the radio control ring	`var(--bq-stroke--tertiary)`
`--bq-radio--border-color-checked`	Border color of the radio control ring when checked	`var(--bq-icon--brand)`
`--bq-radio--dot-color-checked`	Inner dot color when checked	`var(--bq-icon--brand)`
`--bq-radio--label-text-color`	Label text color	`var(--bq-text--primary)`
`--bq-radio--size`	Size (width and height) of the radio control circle	`24px`
`--bq-radio--border-width`	Border width of the radio control ring	`var(--bq-stroke-m)`

Learn more about styling with shadow parts and CSS custom properties.

Resources

Interactive playground

Explore Radio variants and states in Storybook

Source code

View the component source on GitHub

Actions

Data Display

Feedback

Form Controls

Layout

Navigation

When to use

Patterns

Default

Selected

Anatomy

Design guidelines

Usage

Default

Options

Disabled

Horizontal

Fieldset

Background on hover

Form integration

Best practices

Accessibility

Keyboard interaction

Rules

API reference

`bq-radio` properties

`bq-radio-group` properties

Invalid combinations

`bq-radio` methods

`bq-radio` events

`bq-radio-group` events

`bq-radio` slots

`bq-radio-group` slots

`bq-radio` shadow parts

`bq-radio-group` shadow parts

CSS custom properties

Resources

Interactive playground

Source code

​When to use

​Patterns

Default

Selected

​Anatomy

​Design guidelines

​Usage

​Default

​Options

​Disabled

​Horizontal

​Fieldset

​Background on hover

​Form integration

​Best practices

​Accessibility

​Keyboard interaction

​Rules

​API reference

​bq-radio properties

​bq-radio-group properties

​Invalid combinations

​bq-radio methods

​bq-radio events

​bq-radio-group events

​bq-radio slots

​bq-radio-group slots

​bq-radio shadow parts

​bq-radio-group shadow parts

​CSS custom properties

​Resources

Interactive playground

Source code

When to use

Patterns

Anatomy

Design guidelines

Usage

Default

Options

Disabled

Horizontal

Fieldset

Background on hover

Form integration

Best practices

Accessibility

Keyboard interaction

Rules

API reference

`bq-radio` properties

`bq-radio-group` properties

Invalid combinations

`bq-radio` methods

`bq-radio` events

`bq-radio-group` events

`bq-radio` slots

`bq-radio-group` slots

`bq-radio` shadow parts

`bq-radio-group` shadow parts

CSS custom properties

Resources