Skip to main content

Radio

A Radio Group is a collection of individual Radios that allows users to select one option from a small, clearly defined set.

Preferred contact method
Code example
import { Radio, RadioGroup } from '@yleisradio/yds-components-react';

<RadioGroup
  id="contact-pref"
  name="contact"
  label="Preferred contact method"
  selectedValue="email"
  onChange={() => {}}
>
  <Radio value="email" label="Email" />
  <Radio value="sms" label="SMS" />
  <Radio value="phone" label="Phone" />
</RadioGroup>

Why to use​

Radio Groups provide an accessible and consistent way to make a single, mutually exclusive choice. They keep all options visible for easy comparison and clarify the selection context with a shared label, optional description, and unified validation.

When to use​

Use a RadioGroup when users must choose exactly one option from a small, mutually exclusive set and the options should stay visible for comparison. NumericScale when the choice represents a position on a low–high range (e.g., satisfaction, agreement, ratings).

Differences between RadioGroup types​

TypePurposePlacementUse case
RadioGroupOne mutually exclusive choice from a short list.Mostly vertical; horizontal only for short labels.Form questions, settings, preference selections (e.g., “Sähköposti”, “SMS”, “Puhelu”).
NumericScaleChoosing a point on a defined numerical range.Horizontal with clearly labelled endpoints.Ratings, satisfaction scores, Likert-style scales (e.g., “En pitänyt” – “Pidin erittäin paljon”).
Do
  • Use when one option must be selected from a small set.
  • Use when all options should be visible to support quick comparison.
  • Use RadioGroupNumericScale for Likert-style or rating questions.
Don’t
  • Don’t use for multiple selections — use Checkboxes.
  • Don’t use for an instant on/off UI state — use Switch.
  • Don’t use when the list is long or needs searching — use Select or ComboboxSingleSelect.
  • Don’t use when “no selection” is allowed but a single toggle would communicate better — consider Checkbox (single option) or Switch depending on intent.

Content Guidelines​

Radio labels should be short, comparable, and unambiguous so users can scan and understand differences between options quickly.

Do
  • Write a concise group label that reads like a question or heading.(e.g., “Mieluisin yhteydenottotapa”)
  • Keep option labels short and parallel in structure.(e.g., “Sähköposti”, “SMS”, “Puhelu”)
  • Use the group description for brief clarification when needed.
  • For NumericScale, label both ends of the range clearly.(e.g., “En pitänyt” – “Pidin erittäin paljon”)
Don’t
  • Don’t use long sentences as option labels—move explanations to the description.
  • Don’t create overlapping or unclear choices.
  • Don’t repeat label wording in each option.
  • Don’t mix different answer types in one group.

Anatomy​

Radio anatomy

  1. Group label – Defines the purpose of the group.
  2. Description – Optional helper text below the label.
  3. Radio control – Circular selector; only one can be active.
  4. Option label – Text linked to each radio choice.

Key Radio Props​

Use the following props to customize the Radio component to fit your needs.

variant​

ValueExampleDescription
primaryDefault style for most use cases.
secondaryUses highlight color for the control.
Code example
<Radio variant="primary" value="email" label="Email" checked />
<Radio variant="secondary" value="email" label="Email" checked />

isDisabled​

Non-interactive, dimmed styling.

TypeExampleDescription
booleanTemporarily prevents user interaction.
Code example
<Radio value="email" label="Email" isDisabled checked />

hideLabel​

TypeExampleDescription
booleanVisually hides label but keeps it accessible.
Code example
<Radio value="email" label="Email" hideLabel />

controlAlign​

ValueExampleDescription
startPositions the control before the label text.
endPositions the control after the label text.
Code example
<Radio value="email" label="Email" controlAlign="start" />
<Radio value="email" label="Email" controlAlign="end" />

Key RadioGroup Props​

Use the following props to customize the RadioGroup component to fit your needs.

label​

TypeExampleDescription
string
Contact method
Text label describing the purpose of the group.
Code example
<RadioGroup
  id="contact"
  name="contact"
  label="Contact method"
  onChange={() => {}}
>
  <Radio label="Email" value="email" />
  <Radio label="Phone" value="phone" />
</RadioGroup>

description​

Helper guidance placed below the group label.

TypeExampleDescription
string
Contact method
How should we reach you?
Provides additional context or instructions for the group.
Code example
<RadioGroup
  id="contact"
  name="contact"
  label="Contact method"
  description="How should we reach you?"
  onChange={() => {}}
>
  <Radio label="Email" value="email" />
  <Radio label="Phone" value="phone" />
</RadioGroup>

errorMessage​

TypeExampleDescription
string
Contact method
Shows an error message and applies error styles to the group.
Code example
<RadioGroup
  id="contact"
  name="contact"
  label="Contact method"
  errorMessage="Please select a contact method"
  onChange={() => {}}
>
  <Radio label="Email" value="email" />
  <Radio label="Phone" value="phone" />
</RadioGroup>

direction​

Layout orientation of the radio options.

ValueExampleDescription
vertical
Contact method
Stacks radios vertically (default).
horizontal
Contact method
Arranges radios horizontally.
Code example
<RadioGroup
  id="contact"
  name="contact"
  label="Contact method"
  direction="vertical"
  onChange={() => {}}
>
  <Radio label="Email" value="email" />
  <Radio label="Phone" value="phone" />
</RadioGroup>

<RadioGroup
  id="contact"
  name="contact"
  label="Contact method"
  direction="horizontal"
  onChange={() => {}}
>
  <Radio label="Email" value="email" />
  <Radio label="Phone" value="phone" />
</RadioGroup>

RadioGroupNumericScale (Likert / Rating)​

Extends RadioGroup with optional semantic boundary labels.

PropTypeDefaultDescription
startLabelstring—Text describing the low end of the scale (e.g. "Not at all").
endLabelstring—Text describing the high end (e.g. "Very satisfied").
Code example
<RadioGroupNumericScale
  id="satisfaction"
  name="satisfaction"
  label="Satisfaction"
  startLabel="Low"
  endLabel="High"
  direction="horizontal"
  selectedValue="3"
  onChange={() => {}}
>
  <Radio value="1" label="1" />
  <Radio value="2" label="2" />
  <Radio value="3" label="3" />
  <Radio value="4" label="4" />
  <Radio value="5" label="5" />
</RadioGroupNumericScale>

Behavior​

  • Only one option can be selected at a time; choosing a new one deselects the previous.
  • Radios in the same group share the same name attribute to ensure correct selection and navigation.
  • The group label defines the question or context for all options.
  • Use vertical layout for readability and horizontal for compact or scale-type choices.
  • Disabled Radios remain visible but non-interactive.
  • Supports both controlled (selectedValue, onChange) and uncontrolled (defaultChecked) usage.
  • Error messages appear below the group and guide users to correct input.

Accessibility​

Implementation examples​

With description​

Preferred learning method
Choose the learning method that best supports your studying.
Code example
<RadioGroup
  id="newsletter"
  name="newsletter"
  label="Preferred learning method"
  description=" Choose the learning method that best supports your studying."
  selectedValue="weekly"
  onChange={() => {}}
>
  <Radio value="online" label="Online self-paced courses" />
  <Radio value="classroom" label="Instructor-led classroom training" />
  <Radio value="hybrid" label="Hybrid sessions" />
  <Radio value="group" label="Group discussions" />
  <Radio value="independent" label="Independent study" />
</RadioGroup>

With error message​

Preferred learning method
Choose the learning method that best supports your studying.
Code example
<RadioGroup
  id="newsletter"
  name="newsletter"
  label="Preferred learning method"
  description=" Choose the learning method that best supports your studying."
  errorMessage="Please select a preference"
  onChange={() => {}}
>
  <Radio value="online" label="Online self-paced courses" />
  <Radio value="classroom" label="Instructor-led classroom training" />
  <Radio value="hybrid" label="Hybrid sessions" />
  <Radio value="group" label="Group discussions" />
  <Radio value="independent" label="Independent study" />
</RadioGroup>

Numeric scale rating​

Did you like this article?
Did not likeLiked a lot
Code example
<RadioGroupNumericScale
  id="article"
  name="article"
  label="Did you like this article?"
  startLabel="Did not like"
  endLabel="Liked a lot"
  direction="horizontal"
  selectedValue="3"
  onChange={() => {}}
>
  <Radio value="1" label="1" />
  <Radio value="2" label="2" />
  <Radio value="3" label="3" />
  <Radio value="4" label="4" />
  <Radio value="5" label="5" />
</RadioGroupNumericScale>

See more examples in Storybook

API Reference​

Props​

Radio​

The Radio component accepts all standard HTML <input> attributes in addition to the following props:

PropTypeRequiredDefaultDescription
variantVariantTypeNo'primary'
isDisabledbooleanNofalse
errorbooleanNo—
labelReactNodeYes—
namestringNo—
hideLabelbooleanNofalse
useUnderlaybooleanNofalse
onChange(event: ChangeEvent<HTMLInputElement>) => voidNo—
controlAlignInputControlAlignNo'start'

RadioGroup​

The RadioGroup component accepts the following props:

PropTypeRequiredDefaultDescription
idstringYes—
namestringYes—
selectedValuestringNo—
errorMessagestringNo—
labelstringNo—
labelOptionsFormGroupLabelPropsNo—
descriptionstringNo—
childrenReactNodeYes—
directionRadioGroupDirectionNo'vertical'
onChange(event: ChangeEvent<HTMLInputElement>) => voidYes—

RadioGroupNumericScale​

The RadioGroupNumericScale component extends RadioGroup and accepts the following additional props:

PropTypeRequiredDefaultDescription
startLabelstringNo—
endLabelstringNo—

Type Definitions​

Radio​

export type VariantType = 'primary' | 'secondary';
export type InputControlAlign = 'start' | 'end';
export type RadioGroupDirection = 'vertical' | 'horizontal';

export interface RadioDSProps {
  variant?: VariantType;
  isDisabled?: boolean;
  error?: boolean;
  label: ReactNode;
  name?: string;
  hideLabel?: boolean;
  useUnderlay?: boolean;
  onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
  controlAlign?: InputControlAlign;
}

export type RadioProps = InputHTMLAttributes<HTMLInputElement> & RadioDSProps;

RadioGroup​

export interface RadioGroupProps {
  id: string;
  name: string;
  selectedValue?: string;
  errorMessage?: string;
  label?: string;
  labelOptions?: FormGroupLabelProps;
  description?: string;
  children: ReactNode;
  direction?: RadioGroupDirection;
  onChange: (event: ChangeEvent<HTMLInputElement>) => void;
}

RadioGroupNumericScale​

export interface RadioGroupNumericScaleProps extends RadioGroupProps {
  startLabel?: string;
  endLabel?: string;
}
  • Checkbox – For multiple independent selections.
  • Switch – Immediate binary toggles.
  • ChoiceBox – Alternative visual single-choice pattern.
  • Select – Alternative for single selection from a dropdown list.
  • ButtonGroup – Alternative single-selection pattern using buttons.