## Feature Examples

### Structure
- description: The component consists of a radio and label that represents the selection value. By default, `label` is a text string but can be overridden to any other component or a set of components.
- example:
```jsx
<Radio label="Label" />;
```

### States
- description: Control the state of a component with: - `checked` - use it to mark an active selection - `disabled` - use it to mark an item that cannot be selected
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Radio label="Default" />
  <Radio label="Checked" checked />
  <Radio label="Disabled" disabled />
</StorybookComponents.Stack>;
```

### Status message
- description: Add text that explains the status or what action the user should take with the `statusMessage` prop. Show the status message inline, directly below the radio button by wrapping it in a `<FormField/>` and adding `statusMessage`. View more inline status message examples in `<FormField/>`.
- example:
```jsx
<FormField status="error" statusMessage="This is an error message.">
  <Radio label="Radio button" />
</FormField>;
```

### Alignment
- description: Control radio alignment to a label with `alignItems` prop. It supports 2 values: - `center` (default) - use it in all common cases - `top` - use it to align a radio to the top to handle text overflow
- example:
```jsx
<StorybookComponents.Stack width="300px">
  <Radio
    alignItems="top"
    label="Radio button label that wraps to multiple lines"
  />
</StorybookComponents.Stack>;
```

## Common Use Case Examples

### Custom label
- description: Any component or a set of components can be passed as a radio option label.
- example:
```jsx
() => {
  const [checked, setChecked] = React.useState(false);

  return (
    <Radio
      checked={checked}
      onChange={() => setChecked(true)}
      label={
        <Cell>
          <Heading size="small">Free plan</Heading>
          <Text size="small" secondary>
            Offer your plan free of charge.
          </Text>
        </Cell>
      }
    />
  );
};
```

### Additional info
- description: Use `<InfoIcon/>` to provide additional information about a selection.
- example:
```jsx
() => {
  const [checked, setChecked] = React.useState(false);

  return (
    <Box inline gap="6px">
      <Radio
        label="Add total at checkout"
        checked={checked}
        onChange={() => setChecked(true)}
      />
      <InfoIcon content="Tax is charged to a customer, it won't be included in the price of your plans. They'll see it added to the price at a checkout." />
    </Box>
  );
};
```

### Custom layout
- description: A radio can be used to build custom selection lists using `<Card/>` as a base for each option
- example:
```jsx
() => {
  const [checkedId, setCheckedId] = React.useState(0);

  return (
    <Layout cols={1} gap="12px">
      <Card>
        <Box padding="18px 24px">
          <Radio
            checked={checkedId === 1}
            onChange={() => setCheckedId(1)}
            label={
              <Box direction="vertical">
                <Heading size="small">Free plan</Heading>
                <Text size="small" secondary>
                  Offer your plan free of charge
                </Text>
              </Box>
            }
          />
        </Box>
      </Card>
      <Card>
        <Box padding="18px 24px">
          <Radio
            checked={checkedId === 2}
            onChange={() => setCheckedId(2)}
            label={
              <Box direction="vertical">
                <Heading size="small">One time payment</Heading>
                <Text size="small" secondary>
                  Charge a single upfront fee
                </Text>
              </Box>
            }
          />
        </Box>
      </Card>
      <Card>
        <Box padding="18px 24px">
          <Radio
            checked={checkedId === 3}
            onChange={() => setCheckedId(3)}
            label={
              <Box direction="vertical">
                <Heading size="small">Recurring payment</Heading>
                <Text size="small" secondary>
                  Charge a weekly, monthly or yearly fee
                </Text>
              </Box>
            }
          />
        </Box>
      </Card>
    </Layout>
  );
};
```

## Accessibility Examples

### Labelling a radio without visible text
- description: A radio needs an accessible name. When `label` carries the visible text that name comes for free, but a radio labelled only by a graphic or by text elsewhere needs it supplied: - `ariaLabel` gives the radio a name directly, for a control whose meaning is carried by an image or icon. - `ariaLabelledby` points at the id of the element that already labels it, so the name stays in one place. Prefer `ariaLabelledby` when the labelling text is on screen, screen reader users then hear exactly what everyone else reads.
- example:
```jsx
() => {
  const [value, setValue] = React.useState('monthly');

  return (
    <Box direction="vertical" gap="12px">
      <Text id="billing-period-label" weight="bold" size="small">
        Billing period
      </Text>
      <Radio
        label="Monthly"
        ariaLabelledby="billing-period-label"
        checked={value === 'monthly'}
        onChange={() => setValue('monthly')}
      />
      <Radio
        ariaLabel="Yearly billing, two months free"
        checked={value === 'yearly'}
        onChange={() => setValue('yearly')}
        label={<Badge skin="success">Yearly, 2 months free</Badge>}
      />
    </Box>
  );
};
```