XDS — Design System

XDSRadioList@xds/core · RadioList

Preview coming soon

Usage

A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.

Best practices

Guidance	Practices
Do	Keep the number of options small — typically 2 to 7 choices.
Do	Use clear, concise labels that differentiate each option at a glance.
Do	Pre-select a default option when there's a sensible default — don't leave the group empty unless the choice is truly optional.
Don't	Use when multiple selections are needed — use CheckboxList instead.
Don't	Use for long lists — use Selector for better discoverability.
Don't	Use horizontal layout with more than 4 options — it wraps awkwardly.

Anatomy

Element		Description
Header		Optional heading above the radio list.
Children	required	The radio list items rendered as selectable options.
Label/Value	required	The text label and associated value for each radio item.

Import

ts
import {XDSRadioList} from '@xds/core/RadioList'

Props

Prop	Type	Description
labelrequired	string	Label text for the radio group (always rendered for accessibility).
valuerequired	string	The currently selected value.
onChangerequired	(value: string) => void	Callback fired when the selected value changes.
childrenrequired	ReactNode	XDSRadioListItem elements.
isLabelHidden	boolean (default: false)	Whether to visually hide the label.
description	string	Description text displayed below the label.
orientation	'vertical' \| 'horizontal' (default: 'vertical')	Layout direction of the radio items.
isDisabled	boolean (default: false)	Whether all radio items are disabled.
isRequired	boolean (default: false)	Whether the radio group is required.
isOptional	boolean (default: false)	Whether the field is optional (mutually exclusive with isRequired).
status	XDSInputStatus	Status indicator ({ type, message }).
size	'sm' \| 'md' (default: 'md')	Size of the radio controls.
labelTooltip	string	Tooltip text for an info icon next to the label.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Sub-components

RadioList is a compound component with 2 sub-components.

XDSRadioList

Radio group container with field integration for label, description, and status.

Prop	Type	Description
labelrequired	string	Label text for the radio group (always rendered for accessibility).
valuerequired	string	The currently selected value.
onChangerequired	(value: string) => void	Callback fired when the selected value changes.
childrenrequired	ReactNode	XDSRadioListItem elements.
isLabelHidden	boolean (default: false)	Whether to visually hide the label.
description	string	Description text displayed below the label.
orientation	'vertical' \| 'horizontal' (default: 'vertical')	Layout direction of the radio items.
isDisabled	boolean (default: false)	Whether all radio items are disabled.
isRequired	boolean (default: false)	Whether the radio group is required.
isOptional	boolean (default: false)	Whether the field is optional (mutually exclusive with isRequired).
status	XDSInputStatus	Status indicator ({ type, message }).
size	'sm' \| 'md' (default: 'md')	Size of the radio controls.
labelTooltip	string	Tooltip text for an info icon next to the label.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

XDSRadioListItem

Individual radio item with label, description, and content slots.

Prop	Type	Description
labelrequired	string	Label text for the radio item.
valuerequired	string	Value of this radio item.
description	string	Description text displayed below the label.
isDisabled	boolean (default: false)	Whether this individual radio item is disabled.
startContent	ReactNode	Content to render before the radio circle.
endContent	ReactNode	Content to render after the label.

Examples

Common configurations, variations, and states.

RadioList — Horizontal LayoutRadio list with horizontal orientation for compact selections.

tsx
'use client';
import {useState} from 'react';
import {XDSRadioList, XDSRadioListItem} from '@xds/core/RadioList';
export default function RadioListHorizontalLayout() {
  const [value, setValue] = useState('md');
  return (
    <XDSRadioList
      label="Size"
      orientation="horizontal"
      value={value}
      onChange={setValue}>
      <XDSRadioListItem label="Small" value="sm" />
      <XDSRadioListItem label="Medium" value="md" />
      <XDSRadioListItem label="Large" value="lg" />
    </XDSRadioList>
  );
}

RadioList — Pricing TierRadio list with pricing info in end content for plan selection.

tsx
'use client';
import {useState} from 'react';
import {XDSRadioList, XDSRadioListItem} from '@xds/core/RadioList';
import {XDSText} from '@xds/core/Text';
export default function RadioListPricingTier() {
  const [value, setValue] = useState('');
  return (
    <XDSRadioList label="Plan" value={value} onChange={setValue}>
      <XDSRadioListItem
        label="Free"
        value="free"
        endContent={
          <XDSText type="body" color="secondary">
            $0/mo
          </XDSText>
        }
      />
      <XDSRadioListItem
        label="Pro"
        value="pro"
        endContent={
          <XDSText type="body" color="secondary">
            $9/mo
          </XDSText>
        }
      />
      <XDSRadioListItem
        label="Enterprise"
        value="enterprise"
        endContent={
          <XDSText type="body" color="secondary">
            Custom
          </XDSText>
        }
      />
    </XDSRadioList>
  );
}

RadioList — With DescriptionsRadio list with descriptions on the group and each item.

tsx
'use client';
import {useState} from 'react';
import {XDSRadioList, XDSRadioListItem} from '@xds/core/RadioList';
export default function RadioListWithDescriptions() {
  const [value, setValue] = useState('');
  return (
    <XDSRadioList
      label="Notification preference"
      description="Choose how you would like to be notified"
      value={value}
      onChange={setValue}>
      <XDSRadioListItem
        label="Email"
        value="email"
        description="Receive notifications via email"
      />
      <XDSRadioListItem
        label="SMS"
        value="sms"
        description="Standard messaging rates apply"
      />
      <XDSRadioListItem
        label="Push notification"
        value="push"
        description="Instant alerts on your device"
      />
    </XDSRadioList>
  );
}

RadioList — With ValidationRequired radio list with an error message when nothing is selected.

tsx
'use client';
import {useState} from 'react';
import {XDSRadioList, XDSRadioListItem} from '@xds/core/RadioList';
export default function RadioListWithValidation() {
  const [value, setValue] = useState('');
  return (
    <XDSRadioList
      label="Notification preference"
      isRequired
      status={
        value === ''
          ? {type: 'error', message: 'Please select a notification method'}
          : undefined
      }
      value={value}
      onChange={setValue}>
      <XDSRadioListItem label="Email" value="email" />
      <XDSRadioListItem label="SMS" value="sms" />
      <XDSRadioListItem label="Push notification" value="push" />
    </XDSRadioList>
  );
}

Showcase source

tsx
import {XDSRadioList, XDSRadioListItem} from '@xds/core/RadioList';
export default function RadioListShowcase() {
  return (
    <XDSRadioList label="Notification preference" value="" onChange={() => {}}>
      <XDSRadioListItem label="Email" value="email" />
      <XDSRadioListItem label="SMS" value="sms" />
      <XDSRadioListItem label="Push notification" value="push" />
    </XDSRadioList>
  );
}