XDS — Design System

RadioList@xds/core · XDSRadioList v0.0.13

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.

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

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.

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>
  );
}

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.

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

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.

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={{}}.

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.

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> ); }

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> ); }

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> ); }

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> ); }

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> ); }