Radio - Elements

Radios allow users to select a single option from a list of choices.

AndroidreleasedElementsreleasediOSreleasedReactreleasedVuereleased

Example theme:

Accessibility

Usage

A radio input typically consists of two components:

<w-radio-group> - A grouping wrapper that manages labeling, help text, roving keyboard focus, and validation for child radios.
<w-radio> - A single radio with required and invalid states.

In advanced cases you may use <w-radio> without <w-radio-group>. If you're unsure what's correct in your case, always wrap <w-radio> in a <w-radio-group>.

The components automatically handle:

Form integration and constraint validation
Required state handling with validation messages
Accessibility attributes, keyboard interaction, and labeling

html

<w-radio-group label="Select an option" name="usage">
    <w-radio value="one">Option 1</w-radio>
    <w-radio value="two">Option 2</w-radio>
    <w-radio value="three">Option 3</w-radio>
</w-radio-group>

Validation

Set the invalid attribute to display a radio group as invalid, for example if nothing was selected and the group was required.

invalid can be paired with help-text to provide feedback to the user about how to correct the error. However, since the invalid + required use case is so common you can omit help-text to use a generic built-in one.

html

<w-radio-group label="Select an option" name="usage" required invalid>
    <w-radio value="one">Option 1</w-radio>
    <w-radio value="two">Option 2</w-radio>
    <w-radio value="three">Option 3</w-radio>
</w-radio-group>

Examples

html

<w-radio-group label="Select an option" name="examples">
    <w-radio value="one">Option 1</w-radio>
    <w-radio value="two">Option 2</w-radio>
    <w-radio value="three">Option 3</w-radio>
</w-radio-group>

Optional

Add the optional prop to <w-radio-group> to indicate that the user doesn't have to pick an option.

html

<w-radio-group label="Select an option" name="optional" optional>
    <w-radio value="one">Option 1</w-radio>
    <w-radio value="two">Option 2</w-radio>
    <w-radio value="three">Option 3</w-radio>
</w-radio-group>

Help text

Use help-text to give additional context when the label and options are not enough.

html

<w-radio-group label="Select an option" name="help" help-text="Pick whichever you like">
    <w-radio value="one">Option 1</w-radio>
    <w-radio value="two">Option 2</w-radio>
    <w-radio value="three">Option 3</w-radio>
</w-radio-group>

Disabled

Keep in mind that using disabled is an anti-pattern.

There will always be users who don't understand why an element is disabled, or users who can't even see that it is disabled because of poor lighting conditions or other reasons.

Please consider more informative alternatives before choosing to use disabled on an element.

html

<w-radio-group label="Select an option" name="disabled" disabled>
    <w-radio value="one">Option 1</w-radio>
    <w-radio value="two">Option 2</w-radio>
    <w-radio value="three">Option 3</w-radio>
</w-radio-group>

Styling API

This section documents the supported styling hooks for <w-radio> and <w-radio-group>.

Use these hooks to customize appearance without relying on internal structure or selectors.

Before changing the default styles, remember that doing so can result in less consistent experiences for users across the product. Prefer defaults.

Prefer component tokens for size, spacing, and state styling.
Use parts only for small, local tweaks.
Avoid relying on internal class names or selectors.

Parts

The radio exposes a small set of parts that can be targeted for last‑mile layout or typography tweaks.

Part	Targets	Typical use
`control`	radio control (circle)	minor alignment or sizing tweaks
`label`	label content	typography tweaks

Example:

css

w-radio::part(label) {
  font-weight: 600;
}

w-radio::part(control) {
  margin-top: 1px;
}

Parts are intended as an escape hatch. Prefer component tokens for anything state‑ or size‑related.

Component tokens

Component tokens (--w-c-radio-*) act as inputs to the radio styling. They can be set directly on the component or inherited from a parent container.

css

.settings-panel {
  --w-c-radio-gap: 12px;
}

Defaults are defined internally; setting a token is always optional.

Layout & size

Token	Purpose	Default
`--w-c-radio-gap`	space between control and label	`8px`
`--w-c-radio-size`	width/height of the control	`2rem`
`--w-c-radio-radius`	border radius of the control	`50%`
`--w-c-radio-border-width`	border width	`1px`
`--w-c-radio-checked-border-width`	border width when checked	`0.6rem`

Colors

Token	Purpose	Default
`--w-c-radio-bg`	control background	theme default
`--w-c-radio-border-color`	control border color	theme default
`--w-c-radio-border-color-checked`	border color when checked	theme default
`--w-c-radio-label-color`	label text color	`currentColor`

Invalid state

Token	Purpose	Default
`--w-c-radio-border-color-invalid`	border color when invalid	theme default

Disabled state

Token	Purpose	Default
`--w-c-radio-bg-disabled`	background when disabled	theme default
`--w-c-radio-border-color-disabled`	border when disabled	theme default
`--w-c-radio-label-color-disabled`	label color when disabled	theme default
`--w-c-radio-cursor-disabled`	cursor when disabled	`not-allowed`

Typography

Token	Purpose	Default
`--w-c-radio-label-font-size`	label font size	theme default
`--w-c-radio-label-line-height`	label line height	theme default

Focus

Token	Purpose	Default
`--w-c-radio-outline-width`	focus outline width	`2px`
`--w-c-radio-outline-color`	focus outline color	theme default
`--w-c-radio-outline-offset`	focus outline offset	theme default

Interaction

Token	Purpose	Default
`--w-c-radio-cursor`	cursor in enabled state	`pointer`

Motion

Token	Purpose	Default
`--w-c-radio-transition`	transition for control	`150ms cubic-bezier(0.4, 0, 0.2, 1)`

Transitions are automatically disabled when prefers-reduced-motion: reduce is active.

`<w-radio-group>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

Properties

Name	Type	Default	Summary
disabled	`boolean`	`false`	Disables the radio group and all child radios.
help-text	`string`	`''`	Help text for the radio group.
invalid	`boolean`	`false`	Marks the radio group as invalid.
label	`string`	`''`	Label for the radio group.
name	`string \| null`	`null`	The name of the select when submitting the form.
optional	`boolean`	`false`	Whether to show optional text next to the label.
required	`boolean`	`false`	Makes selecting a radio in the the group required.

Property Details

disabled

Disables the radio group and all child radios.

Type: boolean
Default: false

help-text

Help text for the radio group.

If you set required and invalid the group gets a default error message, but you can override it with this attribute.

Type: string
Default: ''

invalid

Marks the radio group as invalid.

Type: boolean
Default: false

label

Label for the radio group.

Type: string
Default: ''

name

The name of the select when submitting the form.

Type: string | null
Default: null

optional

Whether to show optional text next to the label.

Type: boolean
Default: false

required

Makes selecting a radio in the the group required.

Type: boolean
Default: false

`<w-radio>` API

Properties

Name	Type	Default	Summary
checked	`boolean`	`false`	Draws the radio in a checked state (reflected to attribute).
disabled	`boolean`	`false`	Disables the radio.
invalid	`boolean`	`false`	Draws the radio in an invalid state.
name	`string`	`-`	The name of the radio, submitted as a name/value pair with form data.
required	`boolean`	`false`	Makes the radio a required field.
value	`string \| null`	`null`	The radio's value. When selected, the radio group will receive this value.

Property Details

checked

Draws the radio in a checked state (reflected to attribute).

Type: boolean
Default: false

disabled

Disables the radio.

Type: boolean
Default: false

invalid

Draws the radio in an invalid state.

Type: boolean
Default: false

name

The name of the radio, submitted as a name/value pair with form data.

Type: string
Default: -

required

Makes the radio a required field.

Type: boolean
Default: false

value

The radio's value. When selected, the radio group will receive this value.

Type: string | null
Default: null

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system

Radio - Elements ​

Accessibility ​

Usage ​

Validation ​

Examples ​

Optional ​

Help text ​

Disabled ​

Styling API ​

Parts ​

Component tokens ​

Layout & size ​

Colors ​

Invalid state ​

Disabled state ​

Typography ​

Focus ​

Interaction ​

Motion ​

<w-radio-group> API ​

Properties ​

Property Details ​

disabled ​

help-text ​

invalid ​

label ​

name ​

optional ​

required ​

<w-radio> API ​

Properties ​

Property Details ​

checked ​

disabled ​

invalid ​

name ​

required ​

value ​

Questions? ​

Radio - Elements

Accessibility

Usage

Validation

Examples

Optional

Help text

Disabled

Styling API

Parts

Component tokens

Layout & size

Colors

Invalid state

Disabled state

Typography

Focus

Interaction

Motion

`<w-radio-group>` API

Properties

Property Details

disabled

help-text

invalid

label

name

optional

required

`<w-radio>` API

Properties

Property Details

checked

disabled

invalid

name

required

value

Questions?