For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/radio.md.

Radio

Choose one option from a group.

Basic usage

Define choices with RadioGroup.options. Give the group a name with label, aria-label or aria-labelledby. Selected borders use the theme color and pressing keeps the control size unchanged; the selection dot uses a 300ms transition by default.

Choose appearance
basic.tsx
import { RadioGroup } from '@ifhover/leaf-ui';

export function RadioBasic() {
  return (
    <RadioGroup
      label="Choose appearance"
      name="appearance"
      defaultValue="light"
      options={[
        { label: 'Light', value: 'light' },
        { label: 'Dark', value: 'dark' },
        { label: 'System', value: 'system' },
      ]}
    />
  );
}

Examples

Controlled selection

Control the selected string with value, and read event.target.value in onChange.

Notification frequency
Selected: daily
controlled.tsx
import { Flex, RadioGroup, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function RadioControlled() {
  const [value, setValue] = useState('daily');
  return (
    <Flex direction="column" gap="md" align="start">
      <RadioGroup
        label="Notification frequency"
        value={value}
        onChange={(event) => setValue(event.target.value)}
        options={[
          { label: 'Daily', value: 'daily' },
          { label: 'Weekly', value: 'weekly' },
          { label: 'Important messages only', value: 'important' },
        ]}
      />
      <Text tone="muted" role="status">
        Selected: {value}
      </Text>
    </Flex>
  );
}

Vertical layout

Set direction="vertical" for a vertical group.

Notification frequency
vertical.tsx
import { RadioGroup } from '@ifhover/leaf-ui';

export function RadioVertical() {
  return (
    <RadioGroup
      label="Notification frequency"
      direction="vertical"
      defaultValue="daily"
      options={[
        { label: 'Daily', value: 'daily' },
        { label: 'Weekly', value: 'weekly' },
        { label: 'Important messages only', value: 'important' },
      ]}
    />
  );
}

Card choices

Set variant="card" for choices with icons and descriptions.

Backup method
surfaces.tsx
import { RadioGroup } from '@ifhover/leaf-ui';
import { Cloud, HardDrive } from 'lucide-react';

export function RadioCards() {
  return (
    <RadioGroup
      variant="card"
      label={'Backup method'}
      defaultValue="cloud"
      options={[
        {
          value: 'cloud',
          label: 'Cloud backup',
          description: 'Sync across your devices',
          icon: <Cloud />,
        },
        {
          value: 'local',
          label: 'Local backup',
          description: 'Keep data on this device',
          icon: <HardDrive />,
        },
      ]}
    />
  );
}

Grouped choices

Use variant="list" for a shared list. Keep extra to non-interactive status, not buttons or links.

Access policy
list.tsx
import { RadioGroup, Tag } from '@ifhover/leaf-ui';

export function RadioList() {
  return (
    <RadioGroup
      variant="list"
      label={'Access policy'}
      defaultValue="readonly"
      options={[
        {
          value: 'readonly',
          label: 'Read only',
          description: 'Changes require approval',
          extra: (
            <Tag color="success" size="sm">
              {'Recommended'}
            </Tag>
          ),
        },
        {
          value: 'review',
          label: 'Approve every request',
          description: 'Ask the owner to approve every action',
        },
      ]}
    />
  );
}

Forms and reset

Set name to submit the selected option's value. Unselected and disabled options are not submitted. When composing individual Radio controls, use the same name and unique values for each group.

Uncontrolled groups return to defaultValue on form reset. For controlled groups, reset application state as well.

API

Radio API

Configure selection, submission value and disabled state for an individual radio.

Individual Radio controls support native radio attributes. className and style apply to the label container.

PropertyTypeDefaultDescription
size'sm' | 'md' | 'lg''md'Control size
variant'plain' | 'card''plain'Plain choice or a card with a full clickable surface.
descriptionReactNode—Supporting text below the option.
iconReactNode—Leading icon content for the option.
extraReactNode—Supplementary status or tags; avoid interactive controls.
checkedboolean—Controlled checked state.
defaultCheckedboolean—Initial checked state for uncontrolled usage.
valuestring | number | readonly string[]—The value submitted by this radio, not its checked state; use checked for selection.
namestring—Field name in native FormData.
onChangeChangeEventHandler<HTMLInputElement>—Read the selected value from event.target.value.
disabledbooleanfalseDisable interaction.
requiredbooleanfalseRequire a selection among radios with the same name.
childrenReactNode—Clickable choice label.
refRef<HTMLInputElement>—DOM reference

RadioGroup API

Manage the selected value and layout of a group of radio options.

PropertyTypeDefaultDescription
optionsreadonly RadioOption[]RequiredOptions
valuestring—Controlled selected value; the internal uncontrolled value is used when omitted.
defaultValuestring—Initial selected value for uncontrolled usage; native form reset is supported.
namestringGeneratedShared field name; specify it for form submission
labelReactNode—Group name
size'sm' | 'md' | 'lg''md'Control size
variant'plain' | 'card' | 'list''plain'Plain choices, a card grid or a list with shared borders and dividers.
direction'horizontal' | 'vertical''horizontal'Layout direction
requiredbooleanfalseRequire a non-empty value; compound controls validate once.
onChangeChangeEventHandler<HTMLInputElement>—Read event.target.value
disabledbooleanfalseDisable interaction.
refRef<HTMLFieldSetElement>—DOM reference

RadioOption

One group option containing its submission value and displayed content.

PropertyTypeDefaultDescription
labelReactNodeRequiredVisible option content.
descriptionReactNode—Supporting text below the option.
iconReactNode—Leading icon content for the option.
extraReactNode—Supplementary status or tags; avoid interactive controls.
valuestringRequiredOption value; unique within the group.
disabledbooleanfalseDisable the option.