Accordion

Basic Usage

Create an accordion with collapsible items using the block syntax. Combine with other components for rich content.

<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Banff National Park") do %>
    <div class="space-y-3">
      <%= rui_text("Canada's first national park...", size: :sm) %>
      <div class="flex flex-wrap gap-2">
        <%= rui_badge("UNESCO Site", color: :primary, size: :sm) %>
        <%= rui_badge("6,641 km²", color: :success, size: :sm) %>
      </div>
      <%= rui_link("Learn more →", href: "#", size: :sm) %>
    </div>
  <% end %>
  <% accordion.with_item(title: "Niagara Falls") do %>
    ...icons, text, and buttons...
  <% end %>
<% end %>

Colors

Accordions support semantic colors and any Tailwind color that apply to borders, backgrounds, and text.

Semantic Colors

Tailwind Colors

All Tailwind colors are supported with automatic dark mode variants.

<!-- Semantic colors -->
<%= rui_accordion(color: :primary) do |accordion| %>
  <% accordion.with_item(title: "Item 1") do %>
    <div class="space-y-2">...</div>
  <% end %>
<% end %>

<!-- Tailwind colors (all supported!) -->
<%= rui_accordion(color: :red) do |accordion| %>
  <% accordion.with_item(title: "Item 1") do %>...<% end %>
<% end %>
<%= rui_accordion(color: :blue) do |accordion| %>...<% end %>
<%= rui_accordion(color: :purple) do |accordion| %>...<% end %>
<%= rui_accordion(color: :pink) do |accordion| %>...<% end %>

Sizes

Five size options for different contexts. Here featuring classic comedy shows.

<%= rui_accordion(size: :base) do |accordion| %>
  <% accordion.with_item(title: "Friends") do %>
    <div class="space-y-2">
      <%= rui_text("Six friends navigate life...", size: :sm) %>
      <div class="flex items-center gap-3">
        <%= rui_icon(:star, size: :sm, color: :warning) %>
        <%= rui_text("8.9/10 IMDb", size: :sm, weight: :medium) %>
        <%= rui_badge("236 Episodes", size: :sm) %>
      </div>
    </div>
  <% end %>
<% end %>

Variants

Different visual styles for various design contexts. Featuring Canadian cities and provinces.

<%= rui_accordion(variant: :separated) do |accordion| %>
  <% accordion.with_item(title: "Calgary, Alberta") do %>
    <div class="space-y-2">
      <%= rui_text("Gateway to the Canadian Rockies...", size: :sm) %>
      <div class="flex items-center gap-2">
        <%= rui_icon(:mountain, size: :sm) %>
        <%= rui_text("Near Banff", size: :xs, color: :muted) %>
      </div>
    </div>
  <% end %>
<% end %>

Shapes

Control the border radius of accordion items. Here showcasing music genres from around the world.

<%= rui_accordion(shape: :rounded) do |accordion| %>
  <% accordion.with_item(title: "Jazz") do %>
    <div class="space-y-2">
      <%= rui_text("Born in New Orleans...", size: :sm) %>
      <div class="flex gap-2">
        <%= rui_badge("1900s", size: :xs, color: :zinc) %>
        <%= rui_badge("USA", size: :xs, color: :info) %>
      </div>
    </div>
  <% end %>
<% end %>

Item Options

Icons in Headers

Add Lucide icons to accordion headers for visual context.

<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Settings", icon: :settings) do %>
    <%= rui_text("Configure your application settings...", size: :sm, color: :muted) %>
  <% end %>
  <% accordion.with_item(title: "User Profile", icon: :user) do %>
    <%= rui_text("Manage your profile information...", size: :sm, color: :muted) %>
  <% end %>
  <% accordion.with_item(title: "Notifications", icon: :bell) do %>
    <%= rui_text("Control how and when you receive...", size: :sm, color: :muted) %>
  <% end %>
<% end %>

Default Expanded

Set items to be expanded by default.

<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Expanded by Default", expanded: true) do %>
    <%= rui_text("This section is open when the page loads.", size: :sm, color: :muted) %>
  <% end %>
  <% accordion.with_item(title: "Collapsed by Default") do %>
    <%= rui_text("This section starts collapsed.", size: :sm, color: :muted) %>
  <% end %>
<% end %>

Disabled Items

Prevent interaction on specific items.

<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Active Section") do %>
    <%= rui_text("This section can be toggled.", size: :sm, color: :muted) %>
  <% end %>
  <% accordion.with_item(title: "Disabled Section", disabled: true) do %>
    <%= rui_text("This section cannot be opened.", size: :sm, color: :muted) %>
  <% end %>
  <% accordion.with_item(title: "Another Active Section") do %>
    <%= rui_text("This section can also be toggled.", size: :sm, color: :muted) %>
  <% end %>
<% end %>

Subtitles

Add secondary text below the title for additional context.

<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Account Settings", subtitle: "Manage your profile and preferences", icon: :user) do %>
    <%= rui_text("Configure your account details...", size: :sm, color: :muted) %>
  <% end %>
  <% accordion.with_item(title: "Billing", subtitle: "View invoices and payment methods", icon: :credit_card) do %>
    <%= rui_text("Manage your subscription...", size: :sm, color: :muted) %>
  <% end %>
<% end %>

Trailing Icons

Add icons after the title for status indicators.

<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Pro Feature", icon: :star, icon_trailing: :lock) do %>
    <%= rui_text("Upgrade to Pro to unlock this feature.", size: :sm, color: :muted) %>
  <% end %>
  <% accordion.with_item(title: "Completed Task", icon: :check_circle, icon_trailing: :badge_check) do %>
    <%= rui_text("This task has been verified and completed.", size: :sm, color: :muted) %>
  <% end %>
<% end %>

Always-Open Items

Create items that cannot be collapsed - useful for static headers or pinned content.

<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Important Notice", collapsible: false, icon: :alert_circle) do %>
    <%= rui_text("This section is always visible...", size: :sm, color: :muted) %>
  <% end %>
  <% accordion.with_item(title: "Collapsible Section") do %>
    <%= rui_text("This section can be toggled...", size: :sm, color: :muted) %>
  <% end %>
<% end %>

Chevron Options

Chevron Position

Control where the expand/collapse indicator appears. Featuring Canadian cuisine.

<%= rui_accordion(chevron_position: :right) do |accordion| %>
  <% accordion.with_item(title: "Poutine") do %>
    <%= rui_text("Fries topped with cheese curds and gravy...", size: :sm) %>
  <% end %>
<% end %>

<%= rui_accordion(chevron_position: :left) do |accordion| %>
  <% accordion.with_item(title: "Butter Tart") do %>
    <%= rui_text("Sweet pastry with butter, sugar, and egg...", size: :sm) %>
  <% end %>
<% end %>

Custom Expand/Collapse Icons

Use custom icons instead of the default chevron.

<%= rui_accordion(expand_icon: :plus, collapse_icon: :minus) do |accordion| %>
  <% accordion.with_item(title: "Nanaimo Bar") do %>
    <%= rui_text("Three-layer dessert bar...", size: :sm) %>
  <% end %>
<% end %>

<%= rui_accordion(expand_icon: :chevron_down) do |accordion| %>
  <% accordion.with_item(title: "Maple Syrup", expanded: true) do %>
    <%= rui_text("Canada produces 71% of the world's maple syrup.", size: :sm) %>
  <% end %>
<% end %>

Hide Chevron

Remove the expand/collapse icon entirely.

<%= rui_accordion(show_chevron: false) do |accordion| %>
  <% accordion.with_item(title: "BeaverTails", icon: :cookie) do %>
    <%= rui_text("Fried dough pastry shaped like a beaver's tail.", size: :sm) %>
  <% end %>
<% end %>

Dividers

Control the visual separator between items. Featuring Canadian sports.

<%= rui_accordion(dividers: true) do |accordion| %>
  <% accordion.with_item(title: "Hockey") do %>
    <%= rui_text("Canada's national winter sport.", size: :sm) %>
    <%= rui_badge("NHL", size: :xs, color: :primary) %>
  <% end %>
<% end %>

<%= rui_accordion(dividers: false, spacing: :sm) do |accordion| %>
  <% accordion.with_item(title: "Curling") do %>
    <%= rui_text("Strategic ice sport.", size: :sm) %>
  <% end %>
<% end %>

Exclusive Mode

Control whether only one item can be open at a time. Featuring Canadian wildlife.

<%= rui_accordion(exclusive: true) do |accordion| %>
  <% accordion.with_item(title: "Moose") do %>
    <%= rui_text("The largest deer species.", size: :sm) %>
    <%= rui_badge("Up to 700kg", size: :xs) %>
  <% end %>
<% end %>

<%= rui_accordion(exclusive: false) do |accordion| %>
  <% accordion.with_item(title: "Beaver") do %>
    <%= rui_text("Canada's national animal.", size: :sm) %>
  <% end %>
<% end %>

Animation

Toggle smooth expand/collapse animations. Featuring Canadian seasons.

<%= rui_accordion(animate: true) do |accordion| %>
  <% accordion.with_item(title: "Winter") do %>
    <%= rui_text("Snow-covered landscapes...", size: :sm) %>
    <%= rui_badge("-30°C", size: :xs, color: :info) %>
  <% end %>
<% end %>

<%= rui_accordion(animate: false) do |accordion| %>
  <% accordion.with_item(title: "Summer") do %>
    <%= rui_text("Festival season...", size: :sm) %>
  <% end %>
<% end %>

Real-World Examples

FAQ Section

<%= rui_accordion(variant: :separated, color: :primary) do |accordion| %>
  <% accordion.with_item(title: "How do I get started?", icon: :help_circle) do %>
    <div class="space-y-3">
      <%= rui_text("Getting started is easy!", size: :sm, weight: :medium) %>
      <ol class="space-y-2 ml-4">
        <li class="flex items-start gap-2">
          <%= rui_badge(text: "1", color: :primary, size: :xs, shape: :circle) %>
          <%= rui_text("Add the gem to your Gemfile", size: :sm, color: :muted) %>
        </li>
        ...
      </ol>
    </div>
  <% end %>
  <% accordion.with_item(title: "What frameworks are supported?", icon: :code) do %>
    <div class="flex flex-wrap gap-2">
      <%= rui_badge(text: "Rails 7+", color: :danger, size: :sm) %>
      <%= rui_badge(text: "Tailwind CSS", color: :info, size: :sm) %>
    </div>
  <% end %>
<% end %>

User Settings Panel

<%= rui_accordion(variant: :flush, exclusive: false) do |accordion| %>
  <% accordion.with_item(title: "Account Settings", icon: :user, expanded: true) do %>
    <div class="space-y-4 py-2">
      <div class="flex items-center gap-4">
        <%= rui_avatar(name: "John Doe", size: :lg, status: :online) %>
        <div>
          <%= rui_text("John Doe", size: :base, weight: :semibold) %>
          <%= rui_text("john@example.com", size: :sm, color: :muted) %>
        </div>
      </div>
    </div>
  <% end %>
  <% accordion.with_item(title: "Privacy Settings", icon: :shield) do %>
    <div class="flex items-center justify-between">
      <%= rui_text("Profile Visibility", size: :sm, weight: :medium) %>
      <%= rui_badge(text: "Public", color: :success, size: :xs) %>
    </div>
  <% end %>
<% end %>

E-commerce Product Details

<%= rui_accordion(variant: :bordered, size: :sm) do |accordion| %>
  <% accordion.with_item(title: "Description", icon: :file_text, expanded: true) do %>
    <%= rui_text("Premium quality product...", size: :sm, color: :muted) %>
    <div class="flex gap-2 pt-2">
      <%= rui_badge(text: "Eco-Friendly", color: :success, size: :xs) %>
      <%= rui_badge(text: "Handmade", color: :info, size: :xs) %>
    </div>
  <% end %>
  <% accordion.with_item(title: "Customer Reviews", icon: :star) do %>
    <div class="flex items-start gap-3">
      <%= rui_avatar(name: "Sarah M", size: :sm) %>
      <div>
        <div class="flex items-center gap-2">
          <%= rui_text("Sarah M.", size: :sm, weight: :medium) %>
          <%= rui_badge(text: "Verified", color: :success, size: :xs) %>
        </div>
        <%= rui_text("Amazing quality!", size: :sm, color: :muted) %>
      </div>
    </div>
  <% end %>
<% end %>

Team Directory

<%= rui_accordion(variant: :separated, exclusive: false) do |accordion| %>
  <% accordion.with_item(title: "Engineering Team", icon: :code_2, expanded: true) do %>
    <div class="flex items-center justify-between">
      <div class="flex items-center gap-3">
        <%= rui_avatar(name: "Alex Chen", size: :sm, status: :online) %>
        <div>
          <%= rui_link("#", "Alex Chen", size: :sm, weight: :medium, underline: :hover) %>
          <%= rui_text("Tech Lead", size: :xs, color: :muted) %>
        </div>
      </div>
      <%= rui_badge(text: "Lead", color: :primary, size: :xs) %>
    </div>
  <% end %>
<% end %>

Order History

<%= rui_accordion(variant: :bordered) do |accordion| %>
  <% accordion.with_item(title: "Order #12345 - Nov 28, 2024", icon: :package) do %>
    <div class="flex items-center justify-between">
      <%= rui_text("Status", size: :xs, color: :muted, weight: :medium) %>
      <%= rui_badge(text: "Delivered", color: :success, size: :sm) %>
    </div>
    <div class="flex gap-2">
      <%= rui_button("Track Order", size: :sm, variant: :outline) %>
      <%= rui_button("Reorder", size: :sm, color: :primary) %>
    </div>
  <% end %>
<% end %>

Accessibility

The Accordion component follows WAI-ARIA best practices for accessible disclosure widgets.

JavaScript API

The Accordion component exposes Stimulus actions and custom events for programmatic control.

Stimulus Actions

Use these actions via data-action attributes:

<%# Expand/collapse all buttons %>
<div class="flex gap-2 mb-4">
  <button data-action="accordion#expandAll"
          class="px-3 py-1 text-sm bg-zinc-200 rounded">
    Expand All
  </button>
  <button data-action="accordion#collapseAll"
          class="px-3 py-1 text-sm bg-zinc-200 rounded">
    Collapse All
  </button>
</div>

<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Item 1") do %>Content 1<% end %>
  <% accordion.with_item(title: "Item 2") do %>Content 2<% end %>
<% end %>

Custom Events

Listen to these events for lifecycle hooks:

<%# Listen for accordion state changes %>
<div data-controller="my-controller"
     data-action="accordion:expanded->my-controller#onExpand
                  accordion:collapsed->my-controller#onCollapse">
  <%= rui_accordion do |accordion| %>
    <% accordion.with_item(title: "FAQ 1") do %>Answer 1<% end %>
  <% end %>
</div>

<%# In your Stimulus controller %>
// my_controller.js
onExpand(event) {
  const { index, item } = event.detail
  console.log(`Expanded item ${index}`)
}

onCollapse(event) {
  const { index, item } = event.detail
  console.log(`Collapsed item ${index}`)
}

Programmatic Control

Control the accordion from JavaScript using the Stimulus controller:

// Get the accordion controller
const accordionElement = document.querySelector('[data-controller="accordion"]')
const accordionController = application.getControllerForElementAndIdentifier(
  accordionElement,
  "accordion"
)

// Open/close specific items by index
accordionController.open(0)      // Expand first item
accordionController.close(0)     // Collapse first item
accordionController.toggleItem(1) // Toggle second item

// Expand/collapse all
accordionController.expandAll()
accordionController.collapseAll()

// Direct item manipulation
accordionController.expandItem(2)   // Expand with animation
accordionController.collapseItem(2) // Collapse with animation

API Reference