Radio

The Forge Radio component is used to create a form input where only one out of a set of values should be selected.

Option one

Option two

Overview

Radio buttons are selection controls that allow users to select exactly one option from a set of mutually exclusive choices. They appear as small circles that display a filled dot when selected. When a user selects a radio button, any previously selected option in the same group is automatically deselected, ensuring only one choice remains active at a time.

Usage

forge-radio lets a user select a single option from a visible set; group related radios so only one can be checked at a time, either informally by sharing a name or formally inside a forge-radio-group. It’s one of three selection controls — reach for a checkbox when more than one option can be selected, or a switch to turn a single item on or off. When screen space is tight or the set is long, a select compacts the same choice into a closed control.

Rules

Use radios when the user needs to compare all available options at a glance.

Order options logically — alphabetical, numeric, or chronological.

Start each option with a capital letter and use sentence case.

Group related radios in a forge-radio-group with a legend describing the choice.

Use clear, descriptive labels that communicate exactly what will happen when the option is selected.

Provide a default selection when one option is most common or recommended.

Don't

Don't use radios for a large set of options — use a select instead.

Don't use a radio group when more than one option can be selected — use checkboxes instead.

Don't use a single radio for a single yes/no choice — use a checkbox instead.

Grouped options

Wrap related radios in a forge-radio-group (with a forge-label legend describing the choice) so they’re announced as a set and can be disabled together.

Radios grouped inside a forge-radio-group with a shared legend.

<forge-radio-group name="radios">
  <forge-radio name="radios" value="1" label-position>
    Option 1
  </forge-radio>
  <forge-radio name="radios" value="1" label-position>
    Option 2
  </forge-radio>
  <forge-radio name="radios" value="1" label-position>
    Option 3
  </forge-radio>
</forge-radio-group>

Grouping without forge-radio-group

forge-radio-group isn’t required — radios sharing a name already form an implicit group:

<forge-radio name="default">Option 1</forge-radio>
<forge-radio name="default">Option 2</forge-radio>

For a custom layout that still needs to be interpreted as a group, set role="radiogroup" on a plain ancestor element instead:

<div role="radiogroup" aria-label="Choose an option">
  <forge-radio name="default">Option 1</forge-radio>
  <forge-radio name="default">Option 2</forge-radio>
</div>

Label position

Set label-position to start to place the label before the radio instead of after it.

Label position set to start.

<div role="radiogroup" aria-label="Choose an option">
  <forge-radio name="label-position-demo" label-position="start">
    Option 1
  </forge-radio>
  <forge-radio name="label-position-demo" label-position="start">
    Option 2
  </forge-radio>
  <forge-radio name="label-position-demo" label-position="start">
    Option 3
  </forge-radio>
</div>

Disabled and read-only

disabled radios can’t be focused; readonly radios can be focused but not changed.

Disabled radios (left) can't be focused; read-only radios (right) can be focused but not changed.

<div role="radiogroup" aria-label="Disabled example">
  <forge-radio name="disabled-demo" disabled>
    Option 1
  </forge-radio>
  <forge-radio name="disabled-demo" disabled>
    Option 2
  </forge-radio>
</div>
<div role="radiogroup" aria-label="Read-only example">
  <forge-radio name="readonly-demo" readonly checked>
    Option 1
  </forge-radio>
  <forge-radio name="readonly-demo" readonly>
    Option 2
  </forge-radio>
</div>

Dense

Set dense to reduce the radio’s size and spacing.

Dense reduces the radio's size and spacing.

<div role="radiogroup" aria-label="Dense example">
  <forge-radio name="dense-demo" dense>
    Option 1
  </forge-radio>
  <forge-radio name="dense-demo" dense>
    Option 2
  </forge-radio>
  <forge-radio name="dense-demo" dense>
    Option 3
  </forge-radio>
</div>

The Forge Radio component is used to create a form input where only one out of a set of values should be selected.

import "@tylertech/forge/radio";

Properties

Property	Attribute	Type	Default	Description
`checked`	`checked`	`boolean`	`false`	Gets/sets whether the radio is checked.
`defaultChecked`	`default-checked`	`boolean`	`false`	Gets/sets whether the radio is checked by default.
`value`	`value`	`string`	`'on'`	Gets/sets the value of the radio when submitted as part of a form.
`dense`	`dense`	`boolean`	`false`	Controls whether the radio is dense.
`disabled`	`disabled`	`boolean`	`false`	Controls whether the radio is disabled.
`required`	`required`	`boolean`	`false`	Controls whether the radio is required.
`readonly`	`readonly`	`boolean`	`false`	Controls whether the radio is read-only.
`labelPosition`	`label-position`	`RadioLabelPosition`	`'end'`	Controls whether the label appears before or after the radio.

Slots

Name	Description
`(default)`	This is a default/unnamed slot for the label text.

CSS Parts

Name	Description
`::part(root)`	Styles the radio's root element.
`::part(background)`	Styles the border and background of the radio.
`::part(focus-indicator)`	Styles the focus indicator of the radio.
`::part(state-layer)`	Styles the state layer of the radio.

CSS Custom Properties

Name	Description
`--forge-radio-primary-color`	The primary color of the radio button when checked.
`--forge-radio-inactive-color`	The color of the radio button when unchecked.
`--forge-radio-size`	The size of the radio button in the inline and block directions.
`--forge-radio-width`	The width of the radio button.
`--forge-radio-height`	The height of the radio button.
`--forge-radio-border-width`	The width of the radio button's border.
`--forge-radio-unchecked-border-color`	The color of the radio button's border when unchecked.
`--forge-radio-checked-border-color`	The color of the radio button's border when checked.
`--forge-radio-background`	The background of the radio button.
`--forge-radio-shape`	The shape of the radio button.
`--forge-radio-mark-size`	The size of the radio button's mark in the inline and block directions.
`--forge-radio-mark-width`	The width of the radio button's mark.
`--forge-radio-mark-height`	The height of the radio button's mark.
`--forge-radio-mark-color`	The color of the radio button's mark.
`--forge-radio-gap`	The gap between the radio button and its label.
`--forge-radio-justify`	The alignment of the radio button and its label in the inline direction.
`--forge-radio-align`	The alignment of the radio button and its label in the block direction.
`--forge-radio-direction`	The direction of the radio button and its label.
`--forge-radio-state-layer-size`	The size of the radio button's state layer in the inline and block directions.
`--forge-radio-state-layer-width`	The width of the radio button's state layer.
`--forge-radio-state-layer-height`	The height of the radio button's state layer.
`--forge-radio-state-layer-unchecked`	color - The color of the radio button's state layer when unchecked.
`--forge-radio-state-layer-checked-color`	The color of the radio button's state layer when checked.
`--forge-radio-state-layer-shape`	The shape of the radio button's state layer.
`--forge-radio-state-layer-dense-size`	The size of the radio button's state layer when dense.
`--forge-radio-state-layer-dense-width`	The width of the radio button's state layer when dense.
`--forge-radio-state-layer-dense-height`	The height of the radio button's state layer when dense.
`--forge-radio-disabled-opacity`	The opacity of the radio button when disabled.
`--forge-radio-animation-duration`	The duration of the radio button's animations.
`--forge-radio-animation-timing-function`	The timing function of the radio button's animations.
`--forge-radio-animation-delay`	The delay of the radio button's animations.

Keyboard reachability

Ensure every radio is reachable by the tab key and can be selected with the keyboard, not just a pointer.

Group labeling

Radios need to be interpreted as a group by assistive technology, and the group itself needs an accessible name — whichever grouping method you use:

Grouping by a shared name attribute alone doesn’t provide a group label on its own — pair it with one of the two options below.
A plain ancestor element with role="radiogroup" needs an aria-label describing the group’s purpose.
<forge-radio-group> needs a <forge-label legend> (or equivalent) to provide that label.