Radio Group

A set of checkable buttons where only one can be checked at a time.

Stimulus Controller: shadcn--radio-group

FreeProEnterprise

radio-group/default

<%= render Shadcn::RadioGroup.new(name: "plan", value: "pro") do |group| %>
  <% group.with_item(value: "free", label: "Free") %>
  <% group.with_item(value: "pro", label: "Pro") %>
  <% group.with_item(value: "enterprise", label: "Enterprise") %>
<% end %>

Installation

Add the component to your project:

rails generate shadcn:add radio-group

This will also install the Label component if it's not already present.

Usage

<%= render Shadcn::RadioGroup.new(name: "plan", value: "pro") do |group| %>
  <% group.with_item(value: "free", label: "Free") %>
  <% group.with_item(value: "pro", label: "Pro") %>
  <% group.with_item(value: "enterprise", label: "Enterprise") %>
<% end %>

Examples

Horizontal Layout

Set orientation: :horizontal to display radio buttons in a row.

ListGridTable

<div class="flex justify-center">
  <%= render Shadcn::RadioGroup.new(
    name: "layout",
    value: "grid",
    orientation: :horizontal
  ) do |group| %>
    <% group.with_item(value: "list", label: "List") %>
    <% group.with_item(value: "grid", label: "Grid") %>
    <% group.with_item(value: "table", label: "Table") %>
  <% end %>
</div>

With Description

Add descriptive text below each option for clarity.

Free

For individuals just getting started

Pro

For professional developers and small teams

Enterprise

For large organizations with advanced needs

<div class="flex justify-center">
  <div class="max-w-md w-full">
    <%= render Shadcn::RadioGroupComponent.new(name: "plan", value: "pro") do |group| %>
      <% group.with_item(value: "free", label: "Free", description: "For individuals just getting started") %>
      <% group.with_item(value: "pro", label: "Pro", description: "For professional developers and small teams") %>
      <% group.with_item(value: "enterprise", label: "Enterprise", description: "For large organizations with advanced needs") %>
    <% end %>
  </div>
</div>

Disabled State

Individual radio buttons can be disabled.

ComfortableCompact (Disabled)

<div class="flex justify-center">
  <%= render Shadcn::RadioGroupComponent.new(name: "disabled-example", value: "comfortable") do |group| %>
    <% group.with_item(value: "comfortable", label: "Comfortable") %>
    <% group.with_item(value: "compact", label: "Compact (Disabled)", disabled: true) %>
  <% end %>
</div>

Form Integration

The radio group works seamlessly with Rails forms. The name attribute determines the form parameter name.

With Descriptions

All notificationsMentions onlyNo notifications

radio-group/with_descriptions

<%= render Shadcn::RadioGroup.new(name: "notification", value: "all") do |group| %>
  <% group.with_item(value: "all", label: "All notifications", description: "Receive every update as it happens") %>
  <% group.with_item(value: "mentions", label: "Mentions only", description: "Only notify me when someone mentions me") %>
  <% group.with_item(value: "none", label: "No notifications", description: "Turn off all notifications") %>
<% end %>

Card Layout

Hobby - $0/monthPro - $29/monthTeam - $99/month

radio-group/card_layout

<%= render Shadcn::RadioGroup.new(name: "pricing", value: "hobby", class_name: "gap-4") do |group| %>
  <% group.with_item(value: "hobby", label: "Hobby - $0/month") %>
  <% group.with_item(value: "pro", label: "Pro - $29/month") %>
  <% group.with_item(value: "team", label: "Team - $99/month") %>
<% end %>

Required Field

I accept the terms and conditionsI do not accept

radio-group/required

<%= render Shadcn::RadioGroup.new(name: "accept", required: true) do |group| %>
  <% group.with_item(value: "yes", label: "I accept the terms and conditions") %>
  <% group.with_item(value: "no", label: "I do not accept") %>
<% end %>

Color Picker

RedBlueGreenYellow

radio-group/color_picker

<%= render Shadcn::RadioGroup.new(name: "color", value: "blue", orientation: :horizontal) do |group| %>
  <% group.with_item(value: "red", label: "Red") %>
  <% group.with_item(value: "blue", label: "Blue") %>
  <% group.with_item(value: "green", label: "Green") %>
  <% group.with_item(value: "yellow", label: "Yellow") %>
<% end %>

Form Example

Standard Shipping - $5.00Express Shipping - $15.00Overnight Shipping - $25.00

radio-group/form_example

<%= render Shadcn::RadioGroup.new(name: "delivery", value: "standard", class_name: "mt-4") do |group| %>
  <% group.with_item(value: "standard", label: "Standard Shipping - $5.00") %>
  <% group.with_item(value: "express", label: "Express Shipping - $15.00") %>
  <% group.with_item(value: "overnight", label: "Overnight Shipping - $25.00") %>
<% end %>

API Reference

RadioGroupComponent

Prop	Type	Default	Description
name	`String`	`required`	Input name attribute for form submission
value	`String`	`nil`	Currently selected value
disabled	`Boolean`	`false`	Whether the entire group is disabled
required	`Boolean`	`false`	Whether a selection is required
orientation	`Symbol`	`:vertical`	Layout orientation (:vertical or :horizontal)
class_name	`String`	`nil`	Additional CSS classes to apply

RadioGroupItemComponent (via with_item)

Prop	Type	Default	Description
value	`String`	`required`	The value this radio button represents
id	`String`	`nil`	HTML id attribute for label association
disabled	`Boolean`	`false`	Whether this specific item is disabled

Stimulus Controller

The Radio Group component uses the shadcn--radio-group Stimulus controller to handle selection and keyboard navigation.

Features

Click to select radio buttons
Arrow key navigation (Up/Down or Left/Right)
Space/Enter to select focused item
Automatic selection update with visual feedback
Form compatibility with native input events

Events

The controller dispatches a custom shadcn--radio-group:change event when the selection changes.

// Listen for changes
document.addEventListener('shadcn--radio-group:change', (event) => {
  const { value, name } = event.detail
  console.log(`Radio group "${name}" changed to: ${value}`)
})

Targets

Target	Description
item	Individual radio button elements
indicator	Visual indicator (circle) shown when selected

Values

Value	Type	Description
name	String	Input name for form submission
value	String	Currently selected value

Accessibility

Uses role="radiogroup" for the container
Each item has role="radio"
Selection state communicated via aria-checked attribute
Supports keyboard navigation with Arrow keys, Space, and Enter
Only the selected item or first item is in tab order (roving tabindex)
Required state indicated with aria-required
Disabled state indicated with aria-disabled
Associates labels using for and id attributes

Follows the WAI-ARIA Radio Group Pattern.

On This Page

Installation Usage Examples API Reference Stimulus Controller Accessibility