Radio Button Group
Mutually exclusive options with shared validation and required state
Readonly State
Freezes the border color without disabling interaction or graying the tile fill
<div class="nds-form-container nds-radio-container" data-state="readonly">
<div class="nds-form-header">
<label for="radio-readonly1">
<span class="nds-label">Email</span>
<span class="nds-info">Receive updates by email</span>
</label>
</div>
<div class="nds-form-control">
<input type="radio" id="radio-readonly1" name="contact" value="email" class="nds-radio" checked>
</div>
</div>
Built-in Features
What you get out of the box with zero configuration
Form Integration
Auto-initializes with the forms system. Two-way binding syncs disabled and required states between inputs and containers.
Group Validation
Required selection enforced on form submit. Auto-revalidates on change once an error is shown. Call NDS.Forms.clearStatus() to reset.
Visual Feedback
Ripple effect on hover, smooth state transitions, and three sizes (SM, MD, LG) with proportional scaling.
Responsive Layout
Column layout by default, row layout with nds-rowView class. Gaps adjust on mobile for touch-friendly spacing.
Usage Guidelines
When and how to use radio buttons effectively
When to Use
- Selecting exactly one option from a mutually exclusive set
- Use checkboxes when multiple selections are allowed
- Use a select dropdown when there are more than 7 options
- Use switches for instant on/off actions without form submission
- Always provide a default selection when possible to avoid empty submissions
- Wrap options in a fieldset with a legend that describes what the user is choosing
JavaScript API
Modifier Classes
| Class | Target | Description |
|---|---|---|
nds-neutral | .nds-radio | Neutral color variant for the checked tile fill |
nds-md | .nds-radio-container | Medium size: increases tile and gap proportionally, widens gap ring to 4 px |
nds-lg | .nds-radio-container | Large size: further increases tile and gap proportionally, widens gap ring to 5 px |
nds-rowView | .nds-radio-group | Arranges radio options horizontally in a row instead of the default column |
Data Attributes
| Attribute | Target | Description |
|---|---|---|
data-required | .nds-radio-group | Marks the group as required; a selection is enforced on form submit |
data-error-message | .nds-radio-group | Overrides the default validation error message shown when no option is selected |
data-state~="disabled" | .nds-radio-group | Disables all radio inputs in the group via the forms state hook |
data-state~="readonly" | .nds-radio-container | Freezes the tile border to the disabled color while leaving the input interactive |
CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--radio-tile-bg | --background-default | Background fill of the radio tile (unchecked state) |
--radio-tile-border | --controls-border | Outline ring color of the tile (unchecked state) |
--radio-primary-checked | --controls-primary-checked | Tile fill color when the primary radio is checked |
--radio-primary-hovered | --controls-primary-hovered | Tile fill color on hover of a checked primary radio |
--radio-primary-pressed | --controls-primary-pressed | Tile fill color on press of a checked primary radio |
--radio-neutral-checked | --controls-neutral-checked | Tile fill color when the neutral radio is checked |
--radio-neutral-hovered | --controls-neutral-hovered | Tile fill color on hover of a checked neutral radio |
--radio-neutral-pressed | --controls-neutral-pressed | Tile fill color on press of a checked neutral radio |
Validation Attributes
- Add
data-requiredto the group to require a selection before form submission - Add
data-error-messageon the group to override the default validation message - Place a
nds-form-footerwithdata-feedback-targetinside the group for dynamic feedback placement - Use
data-state="disabled"on the group to disable all radio buttons at once