# RapidRailsUI - Complete Documentation
> Production-ready ViewComponent UI library for Ruby on Rails with Tailwind CSS, Hotwire, and Stimulus JS.
This is the complete, detailed documentation file for RapidRailsUI. For a more concise version optimized for AI context windows, see [llms.txt](llms.txt).
**Components**: 31
**Last Updated**: 2026-01-17 at 14:59 EST
---
## Table of Contents
1. [Accordion](#accordion)
2. [Alert](#alert)
3. [Avatar](#avatar)
4. [Badge](#badge)
5. [Button](#button)
6. [Button To](#button-to)
7. [Checkbox](#checkbox)
8. [Clipboard](#clipboard)
9. [Code Block](#code-block)
10. [Combobox](#combobox)
11. [Date](#date)
12. [Dialog](#dialog)
13. [Dropdown](#dropdown)
14. [Editable](#editable)
15. [Icon](#icon)
16. [Image](#image)
17. [Input](#input)
18. [Link](#link)
19. [Live Search](#live-search)
20. [Pagination](#pagination)
21. [Popover](#popover)
22. [Radio Button](#radio-button)
23. [Select](#select)
24. [Social Button](#social-button)
25. [Steps](#steps)
26. [Table](#table)
27. [Text](#text)
28. [Text Fmt](#text-fmt)
29. [Textarea](#textarea)
30. [Tooltip](#tooltip)
31. [Upload](#upload)
---
## Accordion
# Accordion Component
The Accordion component creates collapsible content sections, perfect for FAQs, settings panels, navigation menus, and organizing content into expandable sections.
## Basic Usage
```erb
<%= rui_accordion do |accordion| %>
<% accordion.with_item(title: "What is RapidRailsUI?") do %>
RapidRailsUI is a ViewComponent-based UI library for Rails with full Tailwind CSS integration.
<% end %>
<% accordion.with_item(title: "How do I install it?") do %>
Add the gem to your Gemfile and run the install generator.
<% end %>
<% accordion.with_item(title: "Is it free?") do %>
RapidRailsUI requires a commercial license for production use.
<% end %>
<% end %>
```
## Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `color` | Symbol | `:zinc` | Color theme (`:zinc`, `:gray`, `:slate`, `:primary`, `:secondary`, `:success`, `:warning`, `:danger`, `:info`) |
| `size` | Symbol | `:base` | Size (`:xs`, `:sm`, `:base`, `:lg`, `:xl`) |
| `variant` | Symbol | `:default` | Visual style (`:default`, `:bordered`, `:separated`, `:flush`, `:ghost`) |
| `shape` | Symbol | `:rounded` | Border radius (`:none`, `:rounded`, `:square`, `:pill`) |
| `spacing` | Symbol | `:base` | Space between items (`:none`, `:xs`, `:sm`, `:base`, `:lg`, `:xl`) - used when `dividers: false` or `variant: :separated` |
| `exclusive` | Boolean | `true` | Only allow one item open at a time |
| `animate` | Boolean | `true` | Enable smooth expand/collapse animations |
| `expand_icon` | Symbol | `:chevron_down` | Icon for collapsed state |
| `collapse_icon` | Symbol | `nil` | Icon for expanded state (if nil, expand_icon rotates 180°) |
| `show_chevron` | Boolean | `true` | Show/hide the expand/collapse icon |
| `chevron_position` | Symbol | `:right` | Position of chevron (`:left`, `:right`) |
| `dividers` | Boolean | `true` | Show dividers between items |
### Item Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `title` | String | **required** | Header text for the item |
| `icon` | Symbol | `nil` | Lucide icon name for the header (leading) |
| `icon_trailing` | Symbol | `nil` | Lucide icon name for trailing position |
| `subtitle` | String | `nil` | Secondary text below the title |
| `expanded` | Boolean | `false` | Start with item expanded |
| `disabled` | Boolean | `false` | Disable the item (cannot be toggled) |
| `collapsible` | Boolean | `true` | Whether item can be collapsed (false = always open) |
| `src` | String | `nil` | URL for Turbo Frame lazy loading |
| `loading` | Symbol | `:lazy` | Loading strategy for Turbo Frame (`:lazy`, `:eager`) |
## Variants
### Default
Standard accordion with borders and background.
```erb
<%= rui_accordion(variant: :default) do |accordion| %>
<% accordion.with_item(title: "Section 1") { "Content 1" } %>
<% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```
### Bordered
Thicker borders for more visual emphasis.
```erb
<%= rui_accordion(variant: :bordered) do |accordion| %>
<% accordion.with_item(title: "Section 1") { "Content 1" } %>
<% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```
### Separated
Card-style items with shadows and spacing.
```erb
<%= rui_accordion(variant: :separated, spacing: :lg) do |accordion| %>
<% accordion.with_item(title: "Card 1") { "Content 1" } %>
<% accordion.with_item(title: "Card 2") { "Content 2" } %>
<% end %>
```
### Flush
Minimal style with only bottom borders, no rounded corners.
```erb
<%= rui_accordion(variant: :flush) do |accordion| %>
<% accordion.with_item(title: "Section 1") { "Content 1" } %>
<% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```
### Ghost
No borders or background, just the content.
```erb
<%= rui_accordion(variant: :ghost) do |accordion| %>
<% accordion.with_item(title: "Section 1") { "Content 1" } %>
<% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```
## Colors
### Semantic Colors
```erb
<%# Primary - Blue %>
<%= rui_accordion(color: :primary) do |accordion| %>
<% accordion.with_item(title: "Primary Section") { "Content" } %>
<% end %>
<%# Success - Green %>
<%= rui_accordion(color: :success) do |accordion| %>
<% accordion.with_item(title: "Success Section") { "Content" } %>
<% end %>
<%# Warning - Amber %>
<%= rui_accordion(color: :warning) do |accordion| %>
<% accordion.with_item(title: "Warning Section") { "Content" } %>
<% end %>
<%# Danger - Red %>
<%= rui_accordion(color: :danger) do |accordion| %>
<% accordion.with_item(title: "Danger Section") { "Content" } %>
<% end %>
<%# Info - Sky %>
<%= rui_accordion(color: :info) do |accordion| %>
<% accordion.with_item(title: "Info Section") { "Content" } %>
<% end %>
```
### Neutral Colors
```erb
<%= rui_accordion(color: :zinc) do |accordion| %>
<% accordion.with_item(title: "Zinc Section") { "Content" } %>
<% end %>
<%= rui_accordion(color: :gray) do |accordion| %>
<% accordion.with_item(title: "Gray Section") { "Content" } %>
<% end %>
<%= rui_accordion(color: :slate) do |accordion| %>
<% accordion.with_item(title: "Slate Section") { "Content" } %>
<% end %>
```
## Sizes
```erb
<%# Extra Small %>
<%= rui_accordion(size: :xs) do |accordion| %>
<% accordion.with_item(title: "XS Item") { "Compact content" } %>
<% end %>
<%# Small %>
<%= rui_accordion(size: :sm) do |accordion| %>
<% accordion.with_item(title: "Small Item") { "Small content" } %>
<% end %>
<%# Base (Default) %>
<%= rui_accordion(size: :base) do |accordion| %>
<% accordion.with_item(title: "Base Item") { "Standard content" } %>
<% end %>
<%# Large %>
<%= rui_accordion(size: :lg) do |accordion| %>
<% accordion.with_item(title: "Large Item") { "Larger content" } %>
<% end %>
<%# Extra Large %>
<%= rui_accordion(size: :xl) do |accordion| %>
<% accordion.with_item(title: "XL Item") { "Extra large content" } %>
<% end %>
```
## Icons
Add icons to accordion headers for better visual context.
```erb
<%= rui_accordion do |accordion| %>
<% accordion.with_item(title: "Profile Settings", icon: :user) do %>
Manage your profile information, avatar, and display name.
<% end %>
<% accordion.with_item(title: "Security", icon: :shield) do %>
Update your password and enable two-factor authentication.
<% end %>
<% accordion.with_item(title: "Notifications", icon: :bell) do %>
Configure email and push notification preferences.
<% end %>
<% accordion.with_item(title: "Billing", icon: :credit_card) do %>
View invoices and manage payment methods.
<% end %>
<% end %>
```
### Trailing Icons
Add icons after the title for status indicators or badges.
```erb
<%= rui_accordion do |accordion| %>
<% accordion.with_item(title: "Pro Feature", icon: :star, icon_trailing: :lock) do %>
Upgrade to Pro to unlock this feature.
<% end %>
<% accordion.with_item(title: "Completed", icon: :check_circle, icon_trailing: :badge_check) do %>
This task has been completed.
<% end %>
<% end %>
```
## Subtitles
Add secondary text below the title for additional context.
```erb
<%= rui_accordion do |accordion| %>
<% accordion.with_item(title: "Account Settings", subtitle: "Manage your profile and preferences", icon: :user) do %>
Configure your account details, change email, and update your password.
<% end %>
<% accordion.with_item(title: "Billing", subtitle: "View invoices and payment methods", icon: :credit_card) do %>
Manage your subscription, update payment details, and download invoices.
<% end %>
<% accordion.with_item(title: "Notifications", subtitle: "Control what alerts you receive", icon: :bell) do %>
Choose which notifications to receive via email, SMS, or push.
<% end %>
<% end %>
```
## Chevron Position
Control where the expand/collapse indicator appears.
### Right Position (Default)
```erb
<%= rui_accordion(chevron_position: :right) do |accordion| %>
<% accordion.with_item(title: "Chevron on Right") { "Content" } %>
<% end %>
```
### Left Position
```erb
<%= rui_accordion(chevron_position: :left) do |accordion| %>
<% accordion.with_item(title: "Chevron on Left") { "Content" } %>
<% end %>
```
## Custom Expand/Collapse Icons
Use custom icons instead of the default chevron.
### Plus/Minus Style
```erb
<%= rui_accordion(expand_icon: :plus, collapse_icon: :minus) do |accordion| %>
<% accordion.with_item(title: "Click to Expand") { "Content revealed!" } %>
<% end %>
```
### Circle Plus/Minus Style
```erb
<%= rui_accordion(expand_icon: :circle_plus, collapse_icon: :circle_minus) do |accordion| %>
<% accordion.with_item(title: "Toggle Content") { "Hidden content here." } %>
<% end %>
```
### Rotating Icon (Default Behavior)
When `collapse_icon` is not set, the `expand_icon` rotates 180° when expanded.
```erb
<%= rui_accordion(expand_icon: :chevron_down) do |accordion| %>
<% accordion.with_item(title: "Rotating Chevron") { "Content" } %>
<% end %>
```
## Hide Chevron
Remove the expand/collapse icon entirely.
```erb
<%= rui_accordion(show_chevron: false) do |accordion| %>
<% accordion.with_item(title: "No Chevron", icon: :info) do %>
Click anywhere on the header to toggle.
<% end %>
<% end %>
```
## Dividers
Control the visual separator between items.
### With Dividers (Default)
```erb
<%= rui_accordion(dividers: true) do |accordion| %>
<% accordion.with_item(title: "Section 1") { "Content 1" } %>
<% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```
### Without Dividers (Uses Spacing)
```erb
<%= rui_accordion(dividers: false, spacing: :sm) do |accordion| %>
<% accordion.with_item(title: "Section 1") { "Content 1" } %>
<% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```
## Always-Open Items (Non-Collapsible)
Create items that cannot be collapsed - useful for static headers or pinned content.
```erb
<%= rui_accordion do |accordion| %>
<% accordion.with_item(title: "Important Notice", collapsible: false, icon: :alert_circle) do %>
This section is always visible and cannot be collapsed.
<% end %>
<% accordion.with_item(title: "Collapsible Section") do %>
This section can be toggled open and closed.
<% end %>
<% end %>
```
## Turbo Frame Support (Lazy Loading)
Load content on-demand using Turbo Frames for better performance.
```erb
<%= rui_accordion do |accordion| %>
<% accordion.with_item(title: "Comments", src: comments_path) do %>
<%# Loading placeholder is shown automatically %>
<% end %>
<% accordion.with_item(title: "Activity Log", src: activity_log_path, loading: :lazy) do %>
<%# Content loads when expanded %>
<% end %>
<% accordion.with_item(title: "Preloaded Data", src: data_path, loading: :eager, expanded: true) do %>
<%# Content loads immediately because expanded: true %>
<% end %>
<% end %>
```
### Server-Side Setup
```ruby
# app/controllers/comments_controller.rb
def index
@comments = @post.comments
render partial: "comments/list", locals: { comments: @comments }
end
```
```erb
<%# app/views/comments/_list.html.erb %>
<% comments.each do |comment| %>
<%= comment.body %>
<% end %>
```
## Expanded State
Set items to be expanded by default.
```erb
<%= rui_accordion do |accordion| %>
<% accordion.with_item(title: "Expanded by Default", expanded: true) do %>
This section is open when the page loads.
<% end %>
<% accordion.with_item(title: "Collapsed") do %>
This section starts closed.
<% end %>
<% end %>
```
## Multiple Open Items
Allow multiple items to be open simultaneously by setting `exclusive: false`.
```erb
<%= rui_accordion(exclusive: false) do |accordion| %>
<% accordion.with_item(title: "Section 1", expanded: true) do %>
This can be open...
<% end %>
<% accordion.with_item(title: "Section 2", expanded: true) do %>
...at the same time as this!
<% end %>
<% accordion.with_item(title: "Section 3") do %>
And this one too.
<% end %>
<% end %>
```
## Disabled Items
Prevent specific items from being toggled.
```erb
<%= rui_accordion do |accordion| %>
<% accordion.with_item(title: "Active Section") do %>
This section can be toggled.
<% end %>
<% accordion.with_item(title: "Disabled Section", disabled: true) do %>
This section cannot be opened.
<% end %>
<% end %>
```
## Without Animation
Disable smooth transitions for instant expand/collapse.
```erb
<%= rui_accordion(animate: false) do |accordion| %>
<% accordion.with_item(title: "Instant Toggle") do %>
No animation delay.
<% end %>
<% end %>
```
## Shapes
### Rounded (Default)
```erb
<%= rui_accordion(shape: :rounded) do |accordion| %>
<% accordion.with_item(title: "Rounded Corners") { "Content" } %>
<% end %>
```
### Square
```erb
<%= rui_accordion(shape: :square) do |accordion| %>
<% accordion.with_item(title: "Sharp Corners") { "Content" } %>
<% end %>
```
### Pill
```erb
<%= rui_accordion(shape: :pill) do |accordion| %>
<% accordion.with_item(title: "Extra Rounded") { "Content" } %>
<% end %>
```
## Spacing
Control the gap between accordion items (used when `dividers: false` or `variant: :separated`).
```erb
<%# No spacing %>
<%= rui_accordion(spacing: :none, dividers: false) do |accordion| %>
<% accordion.with_item(title: "Item 1") { "Content" } %>
<% accordion.with_item(title: "Item 2") { "Content" } %>
<% end %>
<%# Large spacing %>
<%= rui_accordion(spacing: :lg, dividers: false) do |accordion| %>
<% accordion.with_item(title: "Item 1") { "Content" } %>
<% accordion.with_item(title: "Item 2") { "Content" } %>
<% end %>
```
## Real-World Examples
### FAQ Section
```erb
<%= rui_text("Frequently Asked Questions", as: :h2, size: :2xl, weight: :bold, class: "mb-6") %>
<%= rui_accordion(color: :primary, variant: :separated, spacing: :base) do |accordion| %>
<% accordion.with_item(title: "How do I get started?", icon: :rocket, subtitle: "Quick setup guide") do %>
<%= rui_text("Getting started is easy:", class: "mb-2") %>
<%= rui_text("Add the gem to your Gemfile") %>
<%= rui_text("Run bundle install") %>
<%= rui_text("Run rails g rapid_rails_ui:install") %>
<%= rui_text("Start using components in your views") %>
<% end %>
<% accordion.with_item(title: "What Rails versions are supported?", icon: :layers, subtitle: "Compatibility info") do %>
<%= rui_text("RapidRailsUI supports Rails 7.0 and above, with full compatibility for Rails 7.1 and 7.2. We recommend using the latest stable Rails release.") %>
<% end %>
<% accordion.with_item(title: "Is Tailwind CSS required?", icon: :palette, subtitle: "Dependencies") do %>
<%= rui_text("Yes, RapidRailsUI is built on Tailwind CSS v4. The install generator will set up Tailwind automatically if it's not already configured.") %>
<% end %>
<% accordion.with_item(title: "Can I customize the components?", icon: :settings, subtitle: "Customization options") do %>
<%= rui_text("Absolutely! You can customize components in several ways:", class: "mb-2") %>
<%= rui_text("Pass custom CSS classes via the class: option") %>
<%= rui_text("Override default colors in your Tailwind config") %>
<%= rui_text("Use the configuration initializer for global defaults") %>
<% end %>
<% end %>
```
### Settings Panel
```erb
<%= rui_accordion(exclusive: false, variant: :bordered) do |accordion| %>
<% accordion.with_item(title: "Account Settings", subtitle: "Manage your profile", icon: :user, expanded: true) do %>
<% end %>
<% accordion.with_item(title: "Privacy", subtitle: "Control your visibility", icon: :eye_off) do %>
<% end %>
<% accordion.with_item(title: "Notifications", subtitle: "Email and push alerts", icon: :bell) do %>
<% end %>
<% end %>
```
### Product Details with Lazy Loading
```erb
<%= rui_accordion(variant: :flush, color: :zinc) do |accordion| %>
<% accordion.with_item(title: "Description", expanded: true) do %>
<%= rui_text("Premium quality product crafted with attention to detail. Made from sustainable materials and designed to last.") %>
<% end %>
<% accordion.with_item(title: "Specifications") do %>
Material
100% Organic Cotton
Weight
180 GSM
Care
Machine wash cold
<% end %>
<% accordion.with_item(title: "Shipping & Returns") do %>
<%= rui_text("Free shipping on orders over $50") %>
<%= rui_text("30-day return policy") %>
<%= rui_text("Ships within 2-3 business days") %>
<% end %>
<%# Lazy load reviews %>
<% accordion.with_item(title: "Reviews (24)", src: product_reviews_path(@product), icon: :star) do %>
<%# Loading spinner shown automatically %>
<% end %>
<% end %>
```
### Navigation Menu with Non-Collapsible Header
```erb
```
### Team Directory with Avatars
```erb
<%= rui_accordion(variant: :separated, spacing: :sm, exclusive: false) do |accordion| %>
<% @teams.each do |team| %>
<% accordion.with_item(
title: team.name,
subtitle: "#{team.members.count} members",
icon: :users
) do %>
<% end %>
<% end %>
<% end %>
```
## Stimulus Controller
The accordion uses a Stimulus controller for interactivity. Make sure to register it:
```javascript
// app/javascript/controllers/index.js
import AccordionController from "rapid_rails_ui/accordion/accordion_controller"
application.register("accordion", AccordionController)
```
### JavaScript API
The controller exposes methods for programmatic control:
```javascript
// Get the controller
const accordion = document.querySelector('[data-controller="accordion"]')
const controller = application.getControllerForElementAndIdentifier(accordion, 'accordion')
// Open item by index
controller.open(0)
// Close item by index
controller.close(0)
// Toggle item by index
controller.toggleItem(1)
// Expand all (only works when exclusive: false)
controller.expandAll()
// Collapse all
controller.collapseAll()
```
### Custom Events
The accordion dispatches events you can listen to:
```javascript
document.addEventListener('accordion:expanded', (event) => {
console.log('Item expanded:', event.detail.index)
})
document.addEventListener('accordion:collapsed', (event) => {
console.log('Item collapsed:', event.detail.index)
})
```
## Accessibility
The accordion follows WAI-ARIA best practices:
- Uses `role="region"` for the accordion container
- Header buttons have `aria-expanded` and `aria-controls` attributes
- Content regions have `aria-labelledby` pointing to their headers
- Non-collapsible items use `