Radio button Overview

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.

When to Use

✅ 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)
Design system docs Examples Basic Usage

Simple radio buttons must be grouped together to ensure mutual exclusivity:

Sizes & Scaling

Choose radio button sizes based on your layout density and visual hierarchy:

Size variations
States & Feedback

Radio buttons support various states to communicate different conditions to users:

Interactive states
Validation states
Label Positioning & Descriptions

Flexible label and description placement for different layout needs:

Label positioning
Description placement
Background & Border Variants

Special styling options for use on colored backgrounds or specific visual emphasis:

Background variant
Border emphasis
Real-World Patterns Survey Question Form
Customer Satisfaction Survey Submit Survey Save for Later
Settings Configuration
Application Settings Save Settings Reset to Defaults
Shipping Options
Delivery Options
Estimated Delivery: Thursday, March 21
Continue to Payment
Accessibility & Keyboard Navigation

The radio button component is designed with accessibility as a core principle:

Keyboard Support
  • 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
Screen Reader Support
  • Proper ARIA labels and descriptions
  • Group labeling for related radio buttons
  • State announcements (checked, unchecked)
  • Form association and validation messages
  • Radio button group context
Focus Management
  • Clear focus indicators
  • Logical tab order within and between groups
  • Programmatic focus control
  • Only checked radio button is focusable by default
Accessibility Examples
Best Practices Form Integration
  • 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)
Visual Design
  • 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
User Experience
  • 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 Organization
  • 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
Importing 
import { DapDSRadioButton } from 'dap-design-system'
Importing React 
import { DapDSRadioButtonReact } from 'dap-design-system/react'
Tree-Shakeable Imports

For optimal bundle sizes, use the tree-shakeable import syntax:

import { DapDSRadioButton } from 'dap-design-system/components'
Attributes
PropertyTypeDefaultDescription
focusablebooleanfalseWhether the radio button is focusable.
posInSetnumber, undefinedPosition in set — set by radio-group for correct screen reader counting
setSizenumber, undefinedSet size — set by radio-group for correct screen reader counting
preventDefaultbooleanfalseWhether the radio button should prevent the default action.
readonlybooleanfalseWhether the radio button is readonly (cannot be changed but value is submitted with form).
borderbooleanfalseThis sets up a border around the radio button, when true.
type'normal', 'background''normal'The type of the radio button.
feedbackIdfeedback-${DapDSRadioButton.nextId}-${uniqueSuffix}
rolestring'radio'
namestringThe name of the radio button.
valuestringThe value of the radio button.
checkedbooleanWhether the radio button is checked.
labelstringThe label of the radio button.
descriptionstringThe description of the radio button.
disabledbooleanWhether the radio button is disabled.
requiredbooleanWhether 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.
subtlebooleanThe weight of the label.
feedbackstringThe feedback of the radio button.
feedbackType'negative', 'positive' , 'warning'The feedback type of the radio button.
invalidbooleanThe invalid state of the radio button.
optionalbooleanThe optional state of the radio button.
optionalLabelstringThe optional label of the radio button.
Slots

No slots available.

Events
Event NameDescriptionType
dds-changeFired when the radio button is checked.{checked: boolean, value: string, disabled: boolean, readonly: boolean, type: 'radio' }
dds-blurEmitted when the radio button loses focus.{void }
dds-focusEmitted when the radio button gains focus.{void }
dds-inputEmitted when the radio button receives input.{checked: boolean, value: string, disabled: boolean, readonly: boolean }
CSS Parts
Part NameDescription
baseThe main radio button container.
wrapperThe wrapper of the radio button.
base-labelThe main label container.
labelThe label of the radio button.
inputThe native input of the radio button.
controlThe control of the radio button.
label-containerThe label container of the radio button.
descriptionThe description of the radio button.
How to Use CSS Parts

You can style CSS parts using the ::part() pseudo-element selector:

/* Target a specific part */
.my-custom-dap-ds-radio-button::part(base) {
  /* Your custom styles */
}

/* Target multiple parts */
.my-custom-dap-ds-radio-button::part(base),
.my-custom-dap-ds-radio-button::part(wrapper) {
  /* Shared styles */
}

Example usage:

<dap-ds-radio-button class="my-custom-dap-ds-radio-button">
  Radio button
</dap-ds-radio-button>

.my-custom-dap-ds-radio-button::part(base) {
  border-radius: 12px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

CSS parts allow you to style internal elements of the component while maintaining encapsulation. Learn more in our styling guide.

 CSS Custom Properties
Property NameDescription
--dds-radio-sizeSets the size of the radio button. (default: var(--dds-spacing-600))
--dds-radio-border-widthSets the border width of the radio button. (default: var(--dds-border-width-large))
--dds-radio-border-radiusSets the border radius of the radio button. (default: var(--dds-radius-rounded))
--dds-radio-border-colorSets the border color of the radio button. (default: var(--dds-border-neutral-base))
--dds-radio-background-colorSets the background color of the radio button. (default: var(--dds-background-neutral-base))
--dds-radio-hover-border-colorSets the border color of the radio button on hover. (default: var(--dds-border-neutral-medium))
--dds-radio-hover-background-colorSets the background color of the radio button on hover. (default: var(--dds-background-neutral-medium))
--dds-radio-active-border-colorSets the border color of the radio button when active. (default: var(--dds-border-neutral-strong))
--dds-radio-active-background-colorSets the background color of the radio button when active. (default: var(--dds-background-neutral-strong))
--dds-radio-checked-background-colorSets the background color of the checked radio button. (default: var(--dds-background-brand-base-inverted))
--dds-radio-checked-hover-background-colorSets the background color of the checked radio button on hover. (default: var(--dds-background-brand-medium-inverted))
--dds-radio-checked-active-background-colorSets the background color of the checked radio button when active. (default: var(--dds-background-brand-strong-inverted))
--dds-radio-disabled-background-colorSets the background color of the disabled radio button. (default: var(--dds-background-neutral-disabled))
--dds-radio-icon-background-colorSets the background color of the radio button icon. (default: var(--dds-transparent-white-strong-static))
--dds-radio-disabled-icon-background-colorSets the background color of the disabled radio button icon. (default: var(--dds-background-neutral-stronger))
--dds-radio-invalid-border-colorSets the border color of the invalid radio button. (default: var(--dds-border-negative-base))
--dds-radio-invalid-background-colorSets the background color of the invalid radio button. (default: var(--dds-background-negative-base))
--dds-radio-invalid-hover-border-colorSets the border color of the invalid radio button on hover. (default: var(--dds-border-negative-medium))
--dds-radio-invalid-hover-background-colorSets the background color of the invalid radio button on hover. (default: var(--dds-background-negative-medium))
--dds-radio-invalid-active-border-colorSets the border color of the invalid radio button when active. (default: var(--dds-border-negative-strong))
--dds-radio-invalid-active-background-colorSets the background color of the invalid radio button when active. (default: var(--dds-background-negative-strong))
--dds-radio-invalid-checked-background-colorSets the background color of the invalid checked radio button. (default: var(--dds-background-negative-base-inverted))
--dds-radio-invalid-checked-hover-background-colorSets the background color of the invalid checked radio button on hover. (default: var(--dds-background-negative-medium-inverted))
--dds-radio-invalid-checked-active-background-colorSets the background color of the invalid checked radio button when active. (default: var(--dds-background-negative-strong-inverted))
--dds-radio-icon-sizeSets the size of the radio button icon. (default: var(--dds-spacing-300))
--dds-radio-readonly-border-colorSets the border color when the radio button is readonly. (default: var(--dds-border-neutral-subtle))
--dds-radio-readonly-background-colorSets the background color when the radio button is readonly. (default: var(--dds-background-neutral-subtle))
--dds-radio-readonly-icon-colorSets the color of the radio button icon when readonly. (default: var(--dds-text-neutral-base))
How to Use CSS Custom Properties

CSS custom properties (CSS variables) can be set directly on the component or in your stylesheet:

Method 1: Inline styles (Quick customization)

<dap-ds-radio-button
  style="--dds-radio-size: value; --dds-radio-border-width: value;">
  Radio button
</dap-ds-radio-button>

Method 2: CSS classes (Reusable styles)

.my-custom-dap-ds-radio-button {
  --dds-radio-size: value;
  --dds-radio-border-width: value;
  --dds-radio-border-radius: value;
}

<dap-ds-radio-button class="my-custom-dap-ds-radio-button">
  Radio button
</dap-ds-radio-button>

Method 3: Global theme customization

/* Apply to all instances */
dap-ds-radio-button {
  --dds-radio-size: value;
  --dds-radio-border-width: value;
}

CSS custom properties inherit through the Shadow DOM, making them perfect for theming. Changes apply immediately without rebuilding.

 Components Radio group <dap-ds-radio-group/> Attributes
PropertyTypeDefaultDescription
tooltipPlacement'top', 'right' , 'bottom' , 'left''bottom'The tooltip placement of the radio group.
hiddenInputHTMLInputElement
optionalLabelstring''Text of optional label.
namestringThe name of the radio group.
valuestringThe value of the radio group.
disabledbooleanWhether the radio group is disabled.
requiredbooleanWhether the radio group is required.
labelstringThe label of the radio group.
descriptionstringThe description of the radio group.
tooltipstringThe tooltip of the radio group.
feedbackstringThe feedback of the radio group.
feedbackType'negative', 'positive' , 'warning'The feedback type of the radio group. Can be negative, positive, or warning.
optionalbooleanThe optional state of the radio group.
subtlebooleanFont weight of the feedback label. Default is false which is bold.
size'xs', 'sm' , 'lg'The size of the radio group. Default is sm.
Slots
NameDescription
(default)The content of the radio group.
feedback-iconThe custom icon of the feedback.
Events
Event NameDescriptionType
dds-changeFired when the radio group is checked.void
dds-blurEmitted when the radio group loses focus.void
dds-focusEmitted when the radio group gains focus.void
CSS Parts
Part NameDescription
baseThe main radio group container.
labelThe label of the radio group.
tooltipThe tooltip of the radio group.
containerThe container of the radio group items.
CSS Custom Properties

No CSS custom properties available.