shadcn-rails

Radio Group

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

Stimulus Controller: shadcn--radio-group

Installation

Add the component to your project:

rails generate shadcn:component radio-group

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

Usage

<%= render Shadcn::RadioGroupComponent.new(name: "notification", value: "email") do |group| %>
  <div class="flex items-center space-x-2">
    <% group.with_item(value: "email", id: "email") %>
    <%= render Shadcn::LabelComponent.new(for: "email") { "Email" } %>
  </div>
  <div class="flex items-center space-x-2">
    <% group.with_item(value: "sms", id: "sms") %>
    <%= render Shadcn::LabelComponent.new(for: "sms") { "SMS" } %>
  </div>
  <div class="flex items-center space-x-2">
    <% group.with_item(value: "push", id: "push") %>
    <%= render Shadcn::LabelComponent.new(for: "push") { "Push Notification" } %>
  </div>
<% end %>

Examples

Horizontal Layout

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

<%= render Shadcn::RadioGroupComponent.new(
  name: "layout",
  value: "grid",
  orientation: :horizontal
) do |group| %>
  <div class="flex items-center space-x-2">
    <% group.with_item(value: "list", id: "list") %>
    <%= render Shadcn::LabelComponent.new(for: "list") { "List" } %>
  </div>
  <div class="flex items-center space-x-2">
    <% group.with_item(value: "grid", id: "grid") %>
    <%= render Shadcn::LabelComponent.new(for: "grid") { "Grid" } %>
  </div>
  <div class="flex items-center space-x-2">
    <% group.with_item(value: "table", id: "table") %>
    <%= render Shadcn::LabelComponent.new(for: "table") { "Table" } %>
  </div>
<% end %>

With Description

Add descriptive text below each option for clarity.

For individuals just getting started

For professional developers and small teams

For large organizations with advanced needs

<%= 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 %>

Disabled State

Individual radio buttons can be disabled.

<%= render Shadcn::RadioGroupComponent.new(name: "disabled-example", value: "comfortable") do |group| %>
  <div class="flex items-center space-x-2">
    <% group.with_item(value: "comfortable", id: "comfortable") %>
    <%= render Shadcn::LabelComponent.new(for: "comfortable") { "Comfortable" } %>
  </div>
  <div class="flex items-center space-x-2">
    <% group.with_item(value: "compact", id: "compact", disabled: true) %>
    <%= render Shadcn::LabelComponent.new(for: "compact") { "Compact (Disabled)" } %>
  </div>
<% end %>

Form Integration

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

<%= form_with url: "/settings", method: :post do |form| %>
  <div class="space-y-4">
    <%= render Shadcn::LabelComponent.new { "Notification Preferences" } %>
    <%= render Shadcn::RadioGroupComponent.new(
      name: "user[notification_method]",
      value: @user.notification_method,
      required: true
    ) do |group| %>
      <div class="flex items-center space-x-2">
        <% group.with_item(value: "email", id: "notify-email") %>
        <%= render Shadcn::LabelComponent.new(for: "notify-email") { "Email" } %>
      </div>
      <div class="flex items-center space-x-2">
        <% group.with_item(value: "sms", id: "notify-sms") %>
        <%= render Shadcn::LabelComponent.new(for: "notify-sms") { "SMS" } %>
      </div>
    <% end %>
    <%= render Shadcn::ButtonComponent.new(type: "submit") { "Save Changes" } %>
  </div>
<% end %>

API Reference

RadioGroupComponent

API Reference

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)

API Reference

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.