Radio Group

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

import type { ChangeEvent, ReactNode } from "react";
import { useId, useState } from "react";

function cx(...parts: Array<string | false | null | undefined>): string {
  return parts.filter(Boolean).join(" ");
}

export interface RadioGroupOption {
  value: string;
  label: ReactNode;
  disabled?: boolean;
  description?: ReactNode;
}

export interface RadioGroupProps {
  legend: ReactNode;
  options: RadioGroupOption[];
  value?: string;
  defaultValue?: string;
  onChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
  disabled?: boolean;
  required?: boolean;
  invalid?: boolean;
  error?: string;
  helperText?: ReactNode;
  name?: string;
  id?: string;
  orientation?: "vertical" | "horizontal";
  className?: string;
}

/**
 * A radio group: only one option may be selected. Wraps native
 * `<input type="radio">` elements sharing a `name` inside a
 * `<fieldset>`/`<legend>`. Controlled (`value`/`onChange`) and uncontrolled
 * (`defaultValue`) modes are both supported.
 */
export function RadioGroup({
  legend,
  options,
  value,
  defaultValue = "",
  onChange,
  disabled,
  required,
  invalid,
  error,
  helperText,
  name,
  id,
  orientation = "vertical",
  className,
}: RadioGroupProps) {
  const generatedId = useId();
  const groupId = id ?? `radio-group-${generatedId}`;
  const groupName = name ?? groupId;
  const messageId = `${groupId}-msg`;
  const isControlled = value !== undefined;
  const [internal, setInternal] = useState<string>(defaultValue);
  const selected = isControlled ? value : internal;

  function handleChange(option: RadioGroupOption, event: ChangeEvent<HTMLInputElement>) {
    if (!isControlled) setInternal(option.value);
    onChange?.(option.value, event);
  }

  const describedby = error || helperText ? messageId : undefined;

  return (
    <fieldset
      id={groupId}
      className={cx("min-w-0 border-0 p-0", className)}
      aria-invalid={invalid || error ? true : undefined}
      aria-describedby={describedby}
    >
      <legend className="mb-2 block text-[13px] font-medium leading-5 text-[var(--ds-color-foreground)]">
        {legend}
        {required ? (
          <span aria-hidden="true" className="ml-0.5 text-[var(--ds-color-destructive)]">*</span>
        ) : null}
      </legend>
      <div className={cx("flex gap-2", orientation === "vertical" ? "flex-col" : "flex-wrap")}>
        {options.map((option) => {
          const isOn = selected === option.value;
          const isDisabled = option.disabled || disabled;
          return (
            <label
              key={option.value}
              htmlFor={`${groupId}-${option.value}`}
              className={cx(
                "inline-flex items-start gap-2.5 text-sm leading-5 text-[var(--ds-color-foreground)]",
                isDisabled ? "cursor-not-allowed opacity-60" : "cursor-pointer",
                orientation === "horizontal" ? "mr-2" : "",
              )}
            >
              <span className="relative mt-[3px] inline-flex size-[18px] shrink-0 items-center justify-center">
                <input
                  id={`${groupId}-${option.value}`}
                  type="radio"
                  name={groupName}
                  value={option.value}
                  checked={isOn}
                  disabled={isDisabled}
                  required={required}
                  aria-invalid={invalid || error ? true : undefined}
                  aria-describedby={option.description ? `${groupId}-${option.value}-desc` : undefined}
                  className={cx(
                    "size-[18px] cursor-pointer appearance-none rounded-full border bg-[var(--ds-color-input)] transition-colors duration-150 ease-out hover:border-[var(--ds-color-border-strong)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--ds-color-focus-ring)] disabled:cursor-not-allowed disabled:opacity-50 motion-reduce:transition-none",
                    invalid || error
                      ? "border-[var(--ds-color-destructive)]"
                      : "border-[var(--ds-color-border)] checked:border-[var(--ds-color-primary)]",
                  )}
                  onChange={(e) => handleChange(option, e)}
                />
                <span
                  aria-hidden="true"
                  className={cx(
                    "pointer-events-none absolute inset-0 flex items-center justify-center transition-opacity duration-150 motion-reduce:transition-none",
                    isOn ? "opacity-100" : "opacity-0",
                  )}
                >
                  <span
                    className={cx(
                      "block size-[8px] rounded-full",
                      invalid || error ? "bg-[var(--ds-color-destructive)]" : "bg-[var(--ds-color-primary)]",
                    )}
                  />
                </span>
              </span>
              <span className="flex flex-col gap-0.5">
                <span className="select-none font-medium">{option.label}</span>
                {option.description ? (
                  <span id={`${groupId}-${option.value}-desc`} className="text-xs leading-4 text-[var(--ds-color-muted-foreground)]">
                    {option.description}
                  </span>
                ) : null}
              </span>
            </label>
          );
        })}
      </div>
      {error ? (
        <p id={messageId} role="alert" className="mt-2 text-xs leading-4 text-[var(--ds-color-destructive)]">
          {error}
        </p>
      ) : helperText ? (
        <p id={messageId} className="mt-2 text-xs leading-4 text-[var(--ds-color-muted-foreground)]">
          {helperText}
        </p>
      ) : null}
    </fieldset>
  );
}

export default RadioGroup;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

/* DevSnips React — JavaScript parity build.
 * Same API, behavior, and classes as code.tsx; TypeScript types removed.
 * Regenerated from code.tsx — edit code.tsx and re-run the generator.
 */

import { useId, useState } from "react";
function cx(...parts) {
  return parts.filter(Boolean).join(" ");
}
export function RadioGroup({
  legend,
  options,
  value,
  defaultValue = "",
  onChange,
  disabled,
  required,
  invalid,
  error,
  helperText,
  name,
  id,
  orientation = "vertical",
  className
}) {
  const generatedId = useId();
  const groupId = id ?? `radio-group-${generatedId}`;
  const groupName = name ?? groupId;
  const messageId = `${groupId}-msg`;
  const isControlled = value !== undefined;
  const [internal, setInternal] = useState(defaultValue);
  const selected = isControlled ? value : internal;
  function handleChange(option, event) {
    if (!isControlled) setInternal(option.value);
    onChange?.(option.value, event);
  }
  const describedby = error || helperText ? messageId : undefined;
  return <fieldset
    id={groupId}
    className={cx("min-w-0 border-0 p-0", className)}
    aria-invalid={invalid || error ? true : undefined}
    aria-describedby={describedby}
  >
      <legend className="mb-2 block text-[13px] font-medium leading-5 text-[var(--ds-color-foreground)]">
        {legend}
        {required ? <span aria-hidden="true" className="ml-0.5 text-[var(--ds-color-destructive)]">*</span> : null}
      </legend>
      <div className={cx("flex gap-2", orientation === "vertical" ? "flex-col" : "flex-wrap")}>
        {options.map((option) => {
    const isOn = selected === option.value;
    const isDisabled = option.disabled || disabled;
    return <label
      key={option.value}
      htmlFor={`${groupId}-${option.value}`}
      className={cx(
        "inline-flex items-start gap-2.5 text-sm leading-5 text-[var(--ds-color-foreground)]",
        isDisabled ? "cursor-not-allowed opacity-60" : "cursor-pointer",
        orientation === "horizontal" ? "mr-2" : ""
      )}
    >
              <span className="relative mt-[3px] inline-flex size-[18px] shrink-0 items-center justify-center">
                <input
      id={`${groupId}-${option.value}`}
      type="radio"
      name={groupName}
      value={option.value}
      checked={isOn}
      disabled={isDisabled}
      required={required}
      aria-invalid={invalid || error ? true : undefined}
      aria-describedby={option.description ? `${groupId}-${option.value}-desc` : undefined}
      className={cx(
        "size-[18px] cursor-pointer appearance-none rounded-full border bg-[var(--ds-color-input)] transition-colors duration-150 ease-out hover:border-[var(--ds-color-border-strong)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--ds-color-focus-ring)] disabled:cursor-not-allowed disabled:opacity-50 motion-reduce:transition-none",
        invalid || error ? "border-[var(--ds-color-destructive)]" : "border-[var(--ds-color-border)] checked:border-[var(--ds-color-primary)]"
      )}
      onChange={(e) => handleChange(option, e)}
    />
                <span
      aria-hidden="true"
      className={cx(
        "pointer-events-none absolute inset-0 flex items-center justify-center transition-opacity duration-150 motion-reduce:transition-none",
        isOn ? "opacity-100" : "opacity-0"
      )}
    >
                  <span
      className={cx(
        "block size-[8px] rounded-full",
        invalid || error ? "bg-[var(--ds-color-destructive)]" : "bg-[var(--ds-color-primary)]"
      )}
    />
                </span>
              </span>
              <span className="flex flex-col gap-0.5">
                <span className="select-none font-medium">{option.label}</span>
                {option.description ? <span id={`${groupId}-${option.value}-desc`} className="text-xs leading-4 text-[var(--ds-color-muted-foreground)]">
                    {option.description}
                  </span> : null}
              </span>
            </label>;
  })}
      </div>
      {error ? <p id={messageId} role="alert" className="mt-2 text-xs leading-4 text-[var(--ds-color-destructive)]">
          {error}
        </p> : helperText ? <p id={messageId} className="mt-2 text-xs leading-4 text-[var(--ds-color-muted-foreground)]">
          {helperText}
        </p> : null}
    </fieldset>;
}

export default RadioGroup;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# Radio Group

Radio group where only one option may be selected, in a fieldset/legend.

## Usage

```tsx
<RadioGroup legend="Deploy target" options={[{value:"production",label:"Production"},{value:"staging",label:"Staging"},{value:"development",label:"Development"}]} defaultValue="staging" />
```

## JavaScript

A `code.jsx` build is provided for projects that ship plain JSX. It exposes the same API and behavior as `code.tsx` — only the TypeScript types are removed.

```jsx
<RadioGroup legend="Deploy target" options={[{value:"production",label:"Production"},{value:"staging",label:"Staging"},{value:"development",label:"Development"}]} defaultValue="staging" />
```

## Props

| Name | Type | Default | Description |
|---|---|---:|---|
| `legend` | `ReactNode` (required) | — | Group label rendered in `<legend>`. |
| `options` | `{value,label,disabled?,description?}[]` (required) | — | Option list. |
| `value` / `defaultValue` | `string` | `""` | Controlled / uncontrolled selected value. |
| `onChange` | `(value, event) => void` | — | Selection callback. |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Layout. |
| `disabled` / `required` / `invalid` / `error` / `helperText` / `name` / `id` | — | — | Standard field props. |

## States

A radio group: only one option may be selected. Wraps native `<input type="radio">` elements sharing a `name` inside a `<fieldset>`/`<legend>`. Controlled (`value`/`onChange`) and uncontrolled (`defaultValue`) modes are both supported. Native arrow-key navigation moves within the named group.

## Accessibility

`<fieldset>` + `<legend>` group labeling. Each native input is wrapped in a `<label htmlFor>`; per-option descriptions are linked with `aria-describedby`. `aria-invalid` + `role="alert"` error message. Visible `focus-visible` ring; arrow keys navigate natively.

## Styling

Built with React, Tailwind CSS, and DevSnips design tokens. The component consumes the `--ds-*` semantic tokens via arbitrary values (for example `bg-[var(--ds-color-primary)]`). Define the tokens once in your theme — no component-specific CSS file is required.

## Design Tokens

See [React/DESIGN_TOKENS.md](../../../DESIGN_TOKENS.md) for the authoritative token specification. This radio uses the semantic color, radius, spacing, and motion tokens.

## Notes

Use this for an exclusive single choice. For multiple independent choices use `checkbox-group`. For card-style options use `radio-card-group`.