The radio button component allows users to select one option from a mutually exclusive set of choices. Unlike checkboxes, radio buttons enforce single selection within a group, making them ideal for decisions where only one answer is appropriate. The component provides clear visual feedback, supports various states including checked, unchecked, and disabled, and is designed with accessibility as a core principle.
✅ Use radio buttons when:
- Users need to select exactly one option from multiple choices
- Options are mutually exclusive (selecting one deselects others)
- All available options should be visible at once
- Building forms with single-choice questions
- Creating filter interfaces with exclusive criteria
- Configuring settings where only one option can be active
❌ Don't use radio buttons for:
- Multiple selection scenarios (use checkboxes instead)
- Binary yes/no choices (consider toggle switches or checkboxes)
- Single options that can be toggled on/off (use checkboxes)
- Navigation or action triggers (use buttons)
- Large sets of options (consider dropdowns or selects)
Simple radio buttons must be grouped together to ensure mutual exclusivity:
Choose radio button sizes based on your layout density and visual hierarchy:
Radio buttons support various states to communicate different conditions to users:
Flexible label and description placement for different layout needs:
Special styling options for use on colored backgrounds or specific visual emphasis:
The radio button component is designed with accessibility as a core principle:
- Arrow Keys: Navigate between radio buttons in a group
- Space: Select the focused radio button
- Enter: Alternative selection method (custom enhancement)
- Tab: Navigate between radio button groups
- Shift + Tab: Navigate backwards between groups
- Proper ARIA labels and descriptions
- Group labeling for related radio buttons
- State announcements (checked, unchecked)
- Form association and validation messages
- Radio button group context
- Clear focus indicators
- Logical tab order within and between groups
- Programmatic focus control
- Only checked radio button is focusable by default
- Always use radio buttons within
dap-ds-radio-group
components - Provide clear, descriptive group labels
- Use descriptions for additional context when needed
- Implement proper validation feedback
- Consider the number of options (use dropdowns for many options)
- Maintain consistent sizing within forms
- Use background variants on colored surfaces
- Consider border emphasis for important selections
- Provide sufficient color contrast
- Test with different themes and accessibility settings
- Limit the number of radio button options (typically 2-7)
- Order options logically (alphabetical, numerical, or by popularity)
- Provide clear feedback for validation states
- Make the most common choice the default selection when appropriate
- Test with real users and assistive technologies
- Group related options together
- Use clear group labels that describe the choice
- Consider progressive disclosure for complex option sets
- Ensure mutual exclusivity is clear to users
- Provide helpful descriptions for complex options
import { DapDSRadioButton } from 'dap-design-system/dist/dds'
import { DapDSRadioButtonReact } from 'dap-design-system/dist/react'
Property | Type | Default | Description |
---|---|---|---|
focusable | boolean | false | Whether the radio button is focusable. |
preventDefault | boolean | false | Whether the radio button should prevent the default action. |
readonly | boolean | false | Whether the radio button is readonly (cannot be changed but value is submitted with form). |
border | boolean | false | This sets up a border around the radio button, when true. |
type | 'normal' , 'background' | 'normal' | The type of the radio button. |
name | string | The name of the radio button. | |
value | string | The value of the radio button. | |
checked | boolean | Whether the radio button is checked. | |
label | string | The label of the radio button. | |
description | string | The description of the radio button. | |
disabled | boolean | Whether the radio button is disabled. | |
required | boolean | Whether the radio button is required. | |
size | 'xs' , 'sm' , 'lg' | The size of the radio button. Default is 'sm'. | |
labelPlacement | 'left' , 'right' | The placement of the label. | |
descriptionPlacement | 'top' , 'bottom' | The placement of the description. | |
subtle | boolean | The weight of the label. | |
feedback | string | The feedback of the radio button. | |
feedbackType | 'negative' , 'positive' , 'warning' | The feedback type of the radio button. | |
invalid | boolean | The invalid state of the radio button. | |
optional | boolean | The optional state of the radio button. | |
optionalLabel | string | The optional label of the radio button. |
No slots available.
Event Name | Description | Type |
---|---|---|
dds-change | Fired when the radio button is checked. | {checked: boolean, value: string, disabled: boolean, readonly: boolean, type: 'radio' } |
dds-blur | Emitted when the radio button loses focus. | {void } |
dds-focus | Emitted when the radio button gains focus. | {void } |
dds-input | Emitted when the radio button receives input. | {checked: boolean, value: string, disabled: boolean, readonly: boolean } |
Part Name | Description |
---|---|
base | The main radio button container. |
wrapper | The wrapper of the radio button. |
base-label | The main label container. |
label | The label of the radio button. |
input | The native input of the radio button. |
control | The control of the radio button. |
label-container | The label container of the radio button. |
description | The description of the radio button. |
Property Name | Description |
---|---|
--dds-radio-size | Sets the size of the radio button. Default: var(--dds-spacing-600) |
--dds-radio-border-width | Sets the border width of the radio button. Default: var(--dds-border-width-large) |
--dds-radio-border-radius | Sets the border radius of the radio button. Default: var(--dds-radius-rounded) |
--dds-radio-border-color | Sets the border color of the radio button. Default: var(--dds-border-neutral-base) |
--dds-radio-background-color | Sets the background color of the radio button. Default: var(--dds-background-neutral-base) |
--dds-radio-hover-border-color | Sets the border color of the radio button on hover. Default: var(--dds-border-neutral-medium) |
--dds-radio-hover-background-color | Sets the background color of the radio button on hover. Default: var(--dds-background-neutral-medium) |
--dds-radio-active-border-color | Sets the border color of the radio button when active. Default: var(--dds-border-neutral-strong) |
--dds-radio-active-background-color | Sets the background color of the radio button when active. Default: var(--dds-background-neutral-strong) |
--dds-radio-checked-background-color | Sets the background color of the checked radio button. Default: var(--dds-background-brand-base-inverted) |
--dds-radio-checked-hover-background-color | Sets the background color of the checked radio button on hover. Default: var(--dds-background-brand-medium-inverted) |
--dds-radio-checked-active-background-color | Sets the background color of the checked radio button when active. Default: var(--dds-background-brand-strong-inverted) |
--dds-radio-disabled-background-color | Sets the background color of the disabled radio button. Default: var(--dds-background-neutral-disabled) |
--dds-radio-icon-background-color | Sets the background color of the radio button icon. Default: var(--dds-transparent-white-strong-static) |
--dds-radio-disabled-icon-background-color | Sets the background color of the disabled radio button icon. Default: var(--dds-background-neutral-stronger) |
--dds-radio-invalid-border-color | Sets the border color of the invalid radio button. Default: var(--dds-border-negative-base) |
--dds-radio-invalid-background-color | Sets the background color of the invalid radio button. Default: var(--dds-background-negative-base) |
--dds-radio-invalid-hover-border-color | Sets the border color of the invalid radio button on hover. Default: var(--dds-border-negative-medium) |
--dds-radio-invalid-hover-background-color | Sets the background color of the invalid radio button on hover. Default: var(--dds-background-negative-medium) |
--dds-radio-invalid-active-border-color | Sets the border color of the invalid radio button when active. Default: var(--dds-border-negative-strong) |
--dds-radio-invalid-active-background-color | Sets the background color of the invalid radio button when active. Default: var(--dds-background-negative-strong) |
--dds-radio-invalid-checked-background-color | Sets the background color of the invalid checked radio button. Default: var(--dds-background-negative-base-inverted) |
--dds-radio-invalid-checked-hover-background-color | Sets the background color of the invalid checked radio button on hover. Default: var(--dds-background-negative-medium-inverted) |
--dds-radio-invalid-checked-active-background-color | Sets the background color of the invalid checked radio button when active. Default: var(--dds-background-negative-strong-inverted) |
--dds-radio-icon-size | Sets the size of the radio button icon. Default: var(--dds-spacing-300) |
--dds-radio-readonly-border-color | Sets the border color when the radio button is readonly. Default is `var(--dds-border-neutral-subtle)`. |
--dds-radio-readonly-background-color | Sets the background color when the radio button is readonly. Default is `var(--dds-background-neutral-subtle)`. |
--dds-radio-readonly-icon-color | Sets the color of the radio button icon when readonly. Default is `var(--dds-text-neutral-base)`. |
Property | Type | Default | Description |
---|---|---|---|
tooltipPlacement | 'top' , 'right' , 'bottom' , 'left' | 'bottom' | The tooltip placement of the radio group. |
hiddenInput | HTMLInputElement | ||
optionalLabel | string | '' | Text of optional label. |
name | string | The name of the radio group. | |
value | string | The value of the radio group. | |
disabled | boolean | Whether the radio group is disabled. | |
required | boolean | Whether the radio group is required. | |
label | string | The label of the radio group. | |
description | string | The description of the radio group. | |
tooltip | string | The tooltip of the radio group. | |
feedback | string | The feedback of the radio group. | |
feedbackType | 'negative' , 'positive' , 'warning' | The feedback type of the radio group. Can be negative , positive , or warning . | |
optional | boolean | The optional state of the radio group. | |
subtle | boolean | Font weight of the feedback label. Default is false which is bold. | |
size | 'xs' , 'sm' , 'lg' | The size of the radio group. Default is sm . |
Name | Description |
---|---|
(default) | The content of the radio group. |
feedback-icon | The custom icon of the feedback. |
Event Name | Description | Type |
---|---|---|
dds-change | Fired when the radio group is checked. | void |
dds-blur | Emitted when the radio group loses focus. | void |
dds-focus | Emitted when the radio group gains focus. | void |
Part Name | Description |
---|---|
base | The main radio group container. |
label | The label of the radio group. |
tooltip | The tooltip of the radio group. |
container | The container of the radio group items. |
No CSS custom properties available.