Radio Group

A group of radio controls for choosing exactly one value.

@data-slot/radio-groupSource ↗

bun add @data-slot/radio-group

npm install @data-slot/radio-group

pnpm add @data-slot/radio-group

Anatomy

Each item needs a data-value. Add data-name to the root and the controller generates hidden native radios that share that field name, so the group submits and resets with the form.

<div data-slot="radio-group" data-default-value="pro" data-name="plan">
  <label>
    <span data-slot="radio-group-item" data-value="starter">
      <span data-slot="radio-group-indicator"></span>
    </span>
    Starter
  </label>

  <label>
    <span data-slot="radio-group-item" data-value="pro">
      <span data-slot="radio-group-indicator"></span>
    </span>
    Pro
  </label>
</div>

Examples

Pick one option

Choose a plan

StarterProEnterprise

Choose a plan

StarterProEnterprise

Show codeHide code

<div class="radio-card">
  <div class="radio-heading" id="radio-group-basic-plan-css-label">Choose a plan</div>
  <div
    data-slot="radio-group"
    data-default-value="pro"
    data-name="plan"
    aria-labelledby="radio-group-basic-plan-css-label"
    class="radio-group"
  >
    <label class="radio-option">
      <span data-slot="radio-group-item" data-value="starter" class="radio-item">
        <span data-slot="radio-group-indicator" class="radio-indicator">
          <span class="radio-dot"></span>
        </span>
      </span>
      Starter
    </label>

    <label class="radio-option">
      <span data-slot="radio-group-item" data-value="pro" class="radio-item">
        <span data-slot="radio-group-indicator" class="radio-indicator">
          <span class="radio-dot"></span>
        </span>
      </span>
      Pro
    </label>

    <label class="radio-option radio-option--disabled">
      <span
        data-slot="radio-group-item"
        data-value="enterprise"
        data-disabled
        class="radio-item"
      >
        <span data-slot="radio-group-indicator" class="radio-indicator">
          <span class="radio-dot"></span>
        </span>
      </span>
      Enterprise
    </label>
  </div>
</div>

<style>
  .radio-card {
    display: grid;
    gap: 0.75rem;
    max-width: 18rem;
  }

  .radio-heading {
    font-size: 0.875rem;
    font-weight: 600;
    color: var(--text);
    line-height: 1.25rem;
  }

  .radio-group {
    display: grid;
    gap: 0.5rem;
    width: 100%;
  }

  .radio-option {
    display: inline-flex;
    align-items: center;
    gap: 0.75rem;
    color: var(--text);
    font-size: 0.875rem;
    line-height: 1.25rem;
  }

  .radio-option--disabled {
    color: var(--muted);
  }

  .radio-item {
    position: relative;
    display: inline-flex;
    width: 1rem;
    height: 1rem;
    flex-shrink: 0;
    align-items: center;
    justify-content: center;
    border: 1px solid var(--muted);
    border-radius: 999px;
    background: var(--surface);
    outline: none;
    transition: border-color 150ms ease, background-color 150ms ease;
  }

  .radio-item[data-checked] {
    background: var(--text);
    border-color: var(--text);
  }

  .radio-item[data-disabled] {
    opacity: 0.5;
    cursor: not-allowed;
  }

  .radio-item:focus-visible {
    box-shadow: 0 0 0 3px color-mix(in srgb, var(--text) 20%, transparent);
  }

  .radio-indicator {
    display: inline-flex;
    width: 1rem;
    height: 1rem;
    align-items: center;
    justify-content: center;
  }

  .radio-dot {
    width: 0.5rem;
    height: 0.5rem;
    border-radius: 999px;
    background: var(--bg);
    opacity: 0;
    transform: scale(0.75);
    transition: opacity 150ms ease, transform 150ms ease;
  }

  .radio-indicator[data-checked] .radio-dot {
    opacity: 1;
    transform: scale(1);
  }
</style>

<div class="grid max-w-72 gap-3">
  <div id="radio-group-basic-plan-tw-label" class="text-sm font-semibold text-text">Choose a plan</div>
  <div
    data-slot="radio-group"
    data-default-value="pro"
    data-name="plan"
    aria-labelledby="radio-group-basic-plan-tw-label"
    class="grid w-full gap-2"
  >
    <label class="inline-flex items-center gap-3 text-sm text-text">
      <span
        data-slot="radio-group-item"
        data-value="starter"
        class="border-[var(--muted)] data-checked:bg-text data-checked:border-text focus-visible:ring-[var(--text)]/20 data-disabled:opacity-50 relative inline-flex size-4 items-center justify-center shrink-0 rounded-full border bg-[var(--surface)] outline-none focus-visible:ring-3"
      >
        <span
          data-slot="radio-group-indicator"
          class="data-unchecked:opacity-0 data-checked:opacity-100 inline-flex size-4 items-center justify-center transition-opacity"
        >
          <span class="size-2 rounded-full bg-[var(--bg)]"></span>
        </span>
      </span>
      Starter
    </label>

    <label class="inline-flex items-center gap-3 text-sm text-text">
      <span
        data-slot="radio-group-item"
        data-value="pro"
        class="border-[var(--muted)] data-checked:bg-text data-checked:border-text focus-visible:ring-[var(--text)]/20 data-disabled:opacity-50 relative inline-flex size-4 items-center justify-center shrink-0 rounded-full border bg-[var(--surface)] outline-none focus-visible:ring-3"
      >
        <span
          data-slot="radio-group-indicator"
          class="data-unchecked:opacity-0 data-checked:opacity-100 inline-flex size-4 items-center justify-center transition-opacity"
        >
          <span class="size-2 rounded-full bg-[var(--bg)]"></span>
        </span>
      </span>
      Pro
    </label>

    <label class="inline-flex items-center gap-3 text-sm text-[var(--muted)]">
      <span
        data-slot="radio-group-item"
        data-value="enterprise"
        data-disabled
        class="border-[var(--muted)] data-checked:bg-text data-checked:border-text data-disabled:opacity-50 relative inline-flex size-4 items-center justify-center shrink-0 rounded-full border bg-[var(--surface)] opacity-50 outline-none"
      >
        <span
          data-slot="radio-group-indicator"
          class="data-unchecked:opacity-0 data-checked:opacity-100 inline-flex size-4 items-center justify-center transition-opacity"
        >
          <span class="size-2 rounded-full bg-[var(--bg)]"></span>
        </span>
      </span>
      Enterprise
    </label>
  </div>
</div>

import { create } from "@data-slot/radio-group";

// Initialize after the markup is in the document.
const controllers = create();

// Clean up before removing the component.
// controllers.forEach((controller) => controller.destroy());

Disabled state

data-disabled on the root disables every item while the current selection stays visible.

Choose a plan

StarterProEnterprise

Choose a plan

StarterProEnterprise

Show codeHide code

<div class="radio-card">
  <div class="radio-heading" id="radio-group-extra-plan-css-label">Choose a plan</div>
  <div
    data-slot="radio-group" data-disabled
    data-default-value="pro"
    data-name="plan"
    aria-labelledby="radio-group-extra-plan-css-label"
    class="radio-group"
  >
    <label class="radio-option">
      <span data-slot="radio-group-item" data-value="starter" class="radio-item">
        <span data-slot="radio-group-indicator" class="radio-indicator">
          <span class="radio-dot"></span>
        </span>
      </span>
      Starter
    </label>

    <label class="radio-option">
      <span data-slot="radio-group-item" data-value="pro" class="radio-item">
        <span data-slot="radio-group-indicator" class="radio-indicator">
          <span class="radio-dot"></span>
        </span>
      </span>
      Pro
    </label>

    <label class="radio-option radio-option--disabled">
      <span
        data-slot="radio-group-item"
        data-value="enterprise"
        data-disabled
        class="radio-item"
      >
        <span data-slot="radio-group-indicator" class="radio-indicator">
          <span class="radio-dot"></span>
        </span>
      </span>
      Enterprise
    </label>
  </div>
</div>

<style>
  .radio-card {
    display: grid;
    gap: 0.75rem;
    max-width: 18rem;
  }

  .radio-heading {
    font-size: 0.875rem;
    font-weight: 600;
    color: var(--text);
    line-height: 1.25rem;
  }

  .radio-group {
    display: grid;
    gap: 0.5rem;
    width: 100%;
  }

  .radio-option {
    display: inline-flex;
    align-items: center;
    gap: 0.75rem;
    color: var(--text);
    font-size: 0.875rem;
    line-height: 1.25rem;
  }

  .radio-option--disabled {
    color: var(--muted);
  }

  .radio-item {
    position: relative;
    display: inline-flex;
    width: 1rem;
    height: 1rem;
    flex-shrink: 0;
    align-items: center;
    justify-content: center;
    border: 1px solid var(--muted);
    border-radius: 999px;
    background: var(--surface);
    outline: none;
    transition: border-color 150ms ease, background-color 150ms ease;
  }

  .radio-item[data-checked] {
    background: var(--text);
    border-color: var(--text);
  }

  .radio-item[data-disabled] {
    opacity: 0.5;
    cursor: not-allowed;
  }

  .radio-item:focus-visible {
    box-shadow: 0 0 0 3px color-mix(in srgb, var(--text) 20%, transparent);
  }

  .radio-indicator {
    display: inline-flex;
    width: 1rem;
    height: 1rem;
    align-items: center;
    justify-content: center;
  }

  .radio-dot {
    width: 0.5rem;
    height: 0.5rem;
    border-radius: 999px;
    background: var(--bg);
    opacity: 0;
    transform: scale(0.75);
    transition: opacity 150ms ease, transform 150ms ease;
  }

  .radio-indicator[data-checked] .radio-dot {
    opacity: 1;
    transform: scale(1);
  }
</style>

<div class="grid max-w-72 gap-3">
  <div id="radio-group-extra-plan-tw-label" class="text-sm font-semibold text-text">Choose a plan</div>
  <div
    data-slot="radio-group" data-disabled
    data-default-value="pro"
    data-name="plan"
    aria-labelledby="radio-group-extra-plan-tw-label"
    class="grid w-full gap-2"
  >
    <label class="inline-flex items-center gap-3 text-sm text-text">
      <span
        data-slot="radio-group-item"
        data-value="starter"
        class="border-[var(--muted)] data-checked:bg-text data-checked:border-text focus-visible:ring-[var(--text)]/20 data-disabled:opacity-50 relative inline-flex size-4 items-center justify-center shrink-0 rounded-full border bg-[var(--surface)] outline-none focus-visible:ring-3"
      >
        <span
          data-slot="radio-group-indicator"
          class="data-unchecked:opacity-0 data-checked:opacity-100 inline-flex size-4 items-center justify-center transition-opacity"
        >
          <span class="size-2 rounded-full bg-[var(--bg)]"></span>
        </span>
      </span>
      Starter
    </label>

    <label class="inline-flex items-center gap-3 text-sm text-text">
      <span
        data-slot="radio-group-item"
        data-value="pro"
        class="border-[var(--muted)] data-checked:bg-text data-checked:border-text focus-visible:ring-[var(--text)]/20 data-disabled:opacity-50 relative inline-flex size-4 items-center justify-center shrink-0 rounded-full border bg-[var(--surface)] outline-none focus-visible:ring-3"
      >
        <span
          data-slot="radio-group-indicator"
          class="data-unchecked:opacity-0 data-checked:opacity-100 inline-flex size-4 items-center justify-center transition-opacity"
        >
          <span class="size-2 rounded-full bg-[var(--bg)]"></span>
        </span>
      </span>
      Pro
    </label>

    <label class="inline-flex items-center gap-3 text-sm text-[var(--muted)]">
      <span
        data-slot="radio-group-item"
        data-value="enterprise"
        data-disabled
        class="border-[var(--muted)] data-checked:bg-text data-checked:border-text data-disabled:opacity-50 relative inline-flex size-4 items-center justify-center shrink-0 rounded-full border bg-[var(--surface)] opacity-50 outline-none"
      >
        <span
          data-slot="radio-group-indicator"
          class="data-unchecked:opacity-0 data-checked:opacity-100 inline-flex size-4 items-center justify-center transition-opacity"
        >
          <span class="size-2 rounded-full bg-[var(--bg)]"></span>
        </span>
      </span>
      Enterprise
    </label>
  </div>
</div>

import { create } from "@data-slot/radio-group";

// Initialize after the markup is in the document.
const controllers = create();

// Clean up before removing the component.
// controllers.forEach((controller) => controller.destroy());

Find and bind uninitialized [data-slot="radio-group"] descendants of scope (defaults to document). Returns RadioGroupController[] for newly bound roots. To initialize the scope element itself, use createRadioGroup.

import { create } from "@data-slot/radio-group";

const controllers = create();

`createRadioGroup(root, options?)`

Create a RadioGroupController for one root element. JavaScript options take precedence over the corresponding data attributes. Calling this again for a bound root returns its existing controller; destroy it before rebinding with new options.

import { createRadioGroup } from "@data-slot/radio-group";

const controller = createRadioGroup(element, {});

Slots

Runtime Slots

radio-group - Root element that manages the selected value, radio-group semantics, and keyboard navigation.
radio-group-item - Individual radio control identified by data-value; receives checked state and participates in roving focus.
radio-group-indicator - Optional visual indicator inside an item; receives checked and disabled state for styling.

Options

Options can be passed via JavaScript or data attributes (JS takes precedence).

Option	Data Attribute	Type	Default	Description
`defaultValue`	`data-default-value`	`string`	`null`	Initially selected value
`name`	`data-name`	`string`	-	Shared form field name for generated radios
`disabled`	`data-disabled`	`boolean`	`false`	Disable user interaction and submission
`readOnly`	`data-read-only` / `data-readOnly`	`boolean`	`false`	Prevent user interaction while keeping programmatic control
`required`	`data-required`	`boolean`	`false`	Require a selected value for native validation
`onValueChange`	-	`(value: string \| null) => void`	-	Callback fired when selection changes

Controller

interface RadioGroupController {
  readonly value: string | null;
  select(value: string): void;
  clear(): void;
  destroy(): void;
}

Events

Outbound Events

Listen for these events on the root element.

Event	Detail	Description
`radio-group:change`	`{ value: string \| null }`	Fires when the selected value changes

Inbound Events

Dispatch these events on the root element.

Event	Detail	Description
`radio-group:set`	`{ value: string \| null }`	Select or clear a value programmatically

// Listen for changes
root.addEventListener("radio-group:change", (e) => {
  console.log("Value:", e.detail.value);
});

// Set value from outside
root.dispatchEvent(
  new CustomEvent("radio-group:set", {
    detail: { value: "pro" },
  }),
);

// Clear selection from outside
root.dispatchEvent(
  new CustomEvent("radio-group:set", {
    detail: { value: null },
  }),
);

Note: Inbound events are blocked when the group is disabled or read-only. Controller methods still work.

Styling

The controller mirrors Base/shadcn-style presence attributes onto items and indicators:

[data-slot="radio-group-item"][data-checked] { ... }
[data-slot="radio-group-item"][data-unchecked] { ... }
[data-slot="radio-group-item"][data-disabled] { ... }
[data-slot="radio-group-indicator"][data-checked] { ... }
[data-slot="radio-group-indicator"][data-unchecked] { ... }

The root also mirrors the current value:

[data-slot="radio-group"][data-value="pro"] { ... }

Key	Action
`ArrowRight` / `ArrowDown`	Move to the next enabled item and select it
`ArrowLeft` / `ArrowUp`	Move to the previous enabled item and select it
`Home`	Select the first enabled item
`End`	Select the last enabled item
`Space` / `Enter`	Select the focused item

Accessibility

Root gets role="radiogroup" plus aria-disabled, aria-readonly, and aria-required
Items get role="radio", aria-checked, aria-disabled, and roving tabindex
Disabled items are skipped during keyboard navigation
Wrapping labels and label[for] associations are mirrored to aria-labelledby

Labeling Patterns

Wrapping Labels

<label>
  <span data-slot="radio-group-item" data-value="starter">
    <span data-slot="radio-group-indicator"></span>
  </span>
  Starter
</label>

Sibling `label[for]`

<label for="plan-pro">Pro</label>
<span id="plan-pro" data-slot="radio-group-item" data-value="pro">
  <span data-slot="radio-group-indicator"></span>
</span>

Form Integration

The controller generates one visually hidden native radio input per item. When name is provided, those inputs share the same field name and participate in native form submission and reset behavior.

<form>
  <div data-slot="radio-group" data-name="plan" data-required>
    <label>
      <span data-slot="radio-group-item" data-value="starter"></span>
      Starter
    </label>
    <label>
      <span data-slot="radio-group-item" data-value="pro"></span>
      Pro
    </label>
  </div>
</form>

Radio Group

Anatomy

Examples

Pick one option

Disabled state

API reference

Initialization

`create(scope?)`

`createRadioGroup(root, options?)`

Slots

Runtime Slots

Options

Controller

Events

Outbound Events

Inbound Events

Styling

Keyboard Navigation

Accessibility

Labeling Patterns

Wrapping Labels

Sibling `label[for]`

Form Integration