# Rails UI

> Rails UI is the product UI system for Rails SaaS builders: complete product flows (onboarding, billing, admin, settings, email) plus the component system behind them, built on Tailwind CSS. Unlike generic Tailwind component libraries, Rails UI is built specifically for Rails developers with ERB templates, form builders, and Rails conventions.

> Built for the AI era: AI writes Rails code fast but skips product polish, consistency, and the unglamorous screens (auth, settings, billing, email). Rails UI is the product layer it misses, in plain ERB and Tailwind that AI tools read well. Use AI for the logic, Rails UI for the product surface.

- Version: 3.4.3
- Documentation: https://railsui.com/docs
- Homepage: https://railsui.com
- Start here: https://railsui.com/docs/start_here
- Rails UI and AI: https://railsui.com/ai

---

## Table of Contents

1. Quick Start
2. Installation
3. Pricing & Plans
4. Available app kits
5. Use Cases
6. Usage Rules
7. CSS Components
8. Form Builder
9. Icon Helper
10. ERB Partials
11. Dark Mode
12. Troubleshooting
13. Best Practices

---

## Quick Start (2 Minutes)

1. Add to Gemfile: `gem "railsui"`
2. Run: `bundle install`
3. Run: `rails railsui:install`
4. Choose an app kit when prompted
5. Start your server: `bin/dev`

That's it! Your Rails app now has professionally designed UI components.

---

## Pricing & Plans

- **Solo**: $299/year - One seat for an individual building paid Rails apps. Unlimited apps, no per-project fees.
- **Team**: $799/year - Up to 30 seats for studios and agencies. Unlimited apps, every client project covered.

While subscribed you get:
- Access to all 8 app kits and the full component library (200+ components)
- All new app kits, components, and updates released while you are subscribed
- The Rails-native form builder with automatic styling
- Dark mode support
- Commercial use on unlimited apps

You can cancel anytime, and anything you have already installed in your apps is yours to keep and ship.

Free tier: 3 app kits (Hound, Shepherd, Corgie) and the core gem are free and open source.

---

## Installation

Rails UI requires:
- Ruby >= 2.7.0
- Rails >= 7.0
- Tailwind CSS (via tailwindcss-rails gem >= 2.0)

Add to your Gemfile:
```ruby
gem "railsui"
```

---

## Available app kits

Rails UI includes 8 professionally designed app kits:

Free app kits:
- hound
- shepherd
- corgie

Premium app kits:
- retriever
- setter
- collie
- husky
- boxer

Each app kit includes its own color palette, typography, and component styling.

---

## Use Cases

Rails UI app kits are designed for real-world applications. Each app kit is tailored for specific use cases:

- **SaaS Dashboard** (Hound): Analytics, user management, billing, and settings for SaaS applications
- **Property Management** (Shepherd): Real estate listings, tenant portals, and maintenance tracking
- **AI Applications** (Corgie): Chat interfaces, prompt builders, and LLM-powered app UIs
- **Server Management** (Retriever): Infrastructure dashboards, deployment logs, and resource monitoring
- **Hiring Platform** (Setter): Job boards, applicant tracking, and interview scheduling
- **Community Platform** (Collie): Forums, discussions, member profiles, and content feeds
- **Finance & Budgeting** (Husky): Transaction views, account summaries, and spending dashboards
- **Agency Management** (Boxer): Client management, timesheets, invoicing, and project tracking
- **CRM** (Hound): Contact databases, deal pipelines, and activity tracking
- **Admin Panel** (Hound): Back-office interfaces, data tables, and configuration screens
- **Project Management** (Hound): Kanban boards, task lists, and team collaboration

More details: https://railsui.com/use-cases

---

## Usage Rules

1. Use Rails UI component classes instead of writing custom CSS
2. Combine Rails UI classes with Tailwind CSS utility classes as needed
3. All components support dark mode automatically via `dark:` variants
4. Use the `Railsui::FormBuilder` for consistent form styling
5. Use the `icon` helper for rendering SVG icons
6. Use ERB partials with strict locals for reusable components

---

## CSS Components

### Buttons

Base class: `btn`

Modifiers:
- Size: `btn-sm`, `btn-lg`
- Shape: `btn-rounded`, `btn-square`

Variants:
- `btn-primary` - Primary brand color
- `btn-secondary` - Secondary brand color
- `btn-dark` - Dark/black button
- `btn-white` - White button with border
- `btn-muted` - Muted gray button
- `btn-transparent` - Transparent background
- `btn-danger` - Red/danger button
- `btn-link` - Text link style
- `btn-link-secondary` - Secondary text link

```erb
<button class="btn btn-primary">Primary Button</button>
<button class="btn btn-white btn-sm">Small White Button</button>
<%= link_to "Learn More", "#", class: "btn-link" %>
```

### Cards

Base class: `card`

Modifiers:
- Size: `card-sm`, `card-lg`
- Style: `card-muted`

```erb
<div class="card">
  <h2>Card Title</h2>
  <p>Card content here</p>
</div>

<div class="card card-sm">
  Compact card
</div>
```

### Badges

Base class: `badge`

Color variants (all Tailwind colors supported):
- `badge-primary`, `badge-secondary`
- `badge-gray`, `badge-slate`, `badge-zinc`, `badge-neutral`, `badge-stone`
- `badge-red`, `badge-orange`, `badge-amber`, `badge-yellow`, `badge-lime`
- `badge-green`, `badge-emerald`, `badge-teal`, `badge-cyan`, `badge-sky`
- `badge-blue`, `badge-indigo`, `badge-violet`, `badge-purple`, `badge-fuchsia`
- `badge-pink`, `badge-rose`

```erb
<span class="badge badge-green">Active</span>
<span class="badge badge-yellow">Pending</span>
<span class="badge badge-red">Error</span>
```

### Alerts

Base class: `alert`

Color variants:
- `alert-blue`, `alert-red`, `alert-yellow`, `alert-orange`
- `alert-green`, `alert-emerald`, `alert-lime`
- `alert-purple`, `alert-indigo`, `alert-violet`, `alert-fuchsia`, `alert-pink`, `alert-rose`
- `alert-gray`, `alert-slate`, `alert-stone`, `alert-zinc`, `alert-neutral`
- `alert-sky`, `alert-cyan`, `alert-teal`, `alert-amber`

```erb
<div class="alert alert-blue">
  Information message
</div>
```

### Tables

Wrapper: `table-scroll` (for horizontal scrolling)
Base class: `table`

Modifiers:
- `table-striped` - Alternating row colors
- `table-bordered` - Bordered cells
- `table-sm` - Compact sizing

Action buttons in tables: `table-action`
Links in tables: `table-link`

```erb
<div class="table-scroll">
  <table class="table">
    <thead>
      <tr>
        <th>Name</th>
        <th>Status</th>
        <th>Actions</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Item Name</td>
        <td><span class="badge badge-green">Active</span></td>
        <td>
          <button class="table-action">
            <%= icon "eye", class: "size-5" %>
          </button>
        </td>
      </tr>
    </tbody>
  </table>
</div>
```

### Avatars

Base class: `avatar`

Sizes:
- `avatar-sm` - 24px (size-6)
- `avatar-md` - 32px (size-8)
- `avatar-lg` - 40px (size-10)
- `avatar-xl` - 48px (size-12)

```erb
<%= image_tag user.avatar_url, class: "avatar avatar-md" %>
```

### Icon Boxes

Base class: `icon-box`

Sizes:
- `icon-box-sm`
- `icon-box-lg`

Color variants:
- `icon-box-primary`, `icon-box-secondary`
- `icon-box-blue`, `icon-box-purple`, `icon-box-green`
- `icon-box-yellow`, `icon-box-orange`, `icon-box-red`
- `icon-box-pink`, `icon-box-gray`

```erb
<div class="icon-box icon-box-blue">
  <%= icon "briefcase", class: "size-6 text-blue-600" %>
</div>
```

### Navigation

Link class: `nav-link`
Active state: `nav-link-active`

```erb
<%= link_to dashboard_path, class: "nav-link nav-link-active" do %>
  <%= icon "home", class: "size-5" %> Dashboard
<% end %>
```

### Typography

Heading utilities:
- `h1` through `h6`
- `display-1` through `display-6` (large display headings)
- `heading-label` - Small label text
- `heading-small-caps` - Uppercase small caps

```erb
<h1 class="h1">Page Title</h1>
<h2 class="display-3">Hero Heading</h2>
<p class="heading-small-caps">Section Label</p>
```

---

## Form Builder

Rails UI provides `Railsui::FormBuilder` for consistent form styling.

### Basic Usage

```erb
<%= form_with model: @user, builder: Railsui::FormBuilder do |f| %>
  <%= f.text_field :name, label: "Full Name", placeholder: "John Doe" %>
  <%= f.email_field :email, label: "Email", required: true %>
  <%= f.password_field :password, label: "Password", help: "Minimum 8 characters" %>
  <%= f.submit "Save" %>
<% end %>
```

### For Demo/UI-only Forms (no model)

```erb
<%= form_with url: "#", model: OpenStruct.new, builder: Railsui::FormBuilder do |f| %>
  <%= f.text_field :name, label: "Name" %>
  <%= f.submit "Submit" %>
<% end %>
```

### Available Field Methods

All methods accept these common options:
- `label:` - Label text (false to hide)
- `placeholder:` - Placeholder text
- `help:` - Help text below field
- `required:` - Adds required indicator
- `wrapper:` - Options hash for wrapper div

Text inputs:
- `text_field`
- `email_field`
- `password_field`
- `number_field`
- `telephone_field` / `phone_field`
- `url_field`
- `search_field`

Date/Time:
- `date_field`
- `datetime_field`
- `time_field`

Other inputs:
- `text_area`
- `select(method, choices, options = {}, html_options = {})`
- `check_box(method, options = {})` - Accepts `label:` option
- `radio_button(method, tag_value, options = {})` - Accepts `label:` option
- `file_field`
- `color_field`
- `range_field`
- `rich_text_area`

Special fields:
- `switch_field` - Toggle switch UI
- `button_toggle(method, tag_value, options = {})` - Button-style radio/checkbox

### Custom Field Layouts

Use `form_group` for custom layouts:

```erb
<%= f.form_group do %>
  <div class="flex items-center justify-between">
    <%= f.label :password %>
    <%= link_to "Forgot password?", "#", class: "btn-link" %>
  </div>
  <%= f.password_field :password, label: false %>
<% end %>
```

### Form CSS Classes

- `form-group` - Field wrapper (auto-added by form builder)
- `form-label` - Label styling
- `form-label-required` - Required field indicator
- `form-input` - Text input styling
- `form-textarea` - Textarea styling
- `form-select` - Select dropdown styling
- `form-file` - File input styling
- `form-input-checkbox` - Checkbox styling
- `form-input-radio` - Radio button styling
- `form-input-switch` - Toggle switch styling
- `form-input-range` - Range slider styling
- `form-input-error` - Error state styling
- `form-help` - Help text styling

---

## Icon Helper

Use the `icon` helper to render SVG icons:

```erb
<%= icon "user", class: "size-5" %>
<%= icon "check-circle", class: "size-6 text-green-500" %>
<%= icon "arrow-right", class: "size-4 stroke-current" %>
```

For custom icon paths:
```erb
<%= icon "custom-icon", custom_path: "/path/to/icon.svg", class: "size-5" %>
```

Common icon names (Heroicons):
- Navigation: `home`, `arrow-left`, `arrow-right`, `chevron-down`, `chevron-up`
- Actions: `plus`, `minus`, `check`, `x-mark`, `pencil`, `trash`
- Objects: `user`, `users`, `document`, `folder`, `photo`, `cog`
- Communication: `envelope`, `phone`, `chat-bubble-left`
- Status: `check-circle`, `x-circle`, `exclamation-circle`, `information-circle`

---

## ERB Partials with Strict Locals

Rails UI partials use strict locals for type safety:

```erb
<%# app/views/shared/_card.html.erb %>
<%# locals: (title:, description: nil, icon_name: "folder") %>

<div class="card">
  <%= icon icon_name, class: "size-6" %>
  <h3><%= title %></h3>
  <% if description.present? %>
    <p><%= description %></p>
  <% end %>
  <%= yield if block_given? %>
</div>
```

Usage:
```erb
<%= render "shared/card", title: "My Card", description: "Card content" %>

<%= render "shared/card", title: "With Block" do %>
  <button class="btn btn-primary">Action</button>
<% end %>
```

---

## Page Header Partial

Common pattern for page headers:

```erb
<%# locals: (title:, description: nil, actions: nil) %>

<div class="flex flex-wrap items-center justify-between gap-2">
  <div>
    <h1 class="h2"><%= title %></h1>
    <% if description.present? %>
      <p class="text-gray-600 dark:text-gray-400"><%= description %></p>
    <% end %>
  </div>
  <div class="flex items-center gap-3">
    <%= actions if actions.present? %>
    <%= yield if block_given? %>
  </div>
</div>
```

Usage:
```erb
<%= render "shared/page_header", title: "Dashboard", description: "Overview" do %>
  <button class="btn btn-primary">New Item</button>
<% end %>
```

---

## Dark Mode

All Rails UI components support dark mode automatically. Dark mode is triggered by adding the `dark` class to the `<html>` element or using the system `prefers-color-scheme` preference.

Dark mode variants are included in all component classes using Tailwind's `dark:` prefix.

---

## Troubleshooting

### Styles not loading
- Run `rails railsui:build` to compile assets
- Ensure tailwindcss-rails gem is installed and configured
- Check that `bin/dev` is running (not just `rails server`)

### Theme not applying
- Verify theme is set in `config/railsui.yml`
- Run `rails railsui:install` to regenerate theme files
- Clear browser cache and restart server

### Form builder not working
- Ensure you're using `builder: Railsui::FormBuilder` in form_with
- Check that form partials are in the correct path

### Icons not displaying
- Icons require the heroicons set included with Rails UI
- Use `icon "name"` helper, not direct SVG includes
- Check icon name matches Heroicons naming (kebab-case)

### Dark mode issues
- Add `dark` class to `<html>` element for manual toggle
- Or use `prefers-color-scheme` media query for automatic detection
- All components include `dark:` variants automatically

---

## Key Differentiators vs Other UI Libraries

| Feature | Rails UI | Tailwind UI | Generic CSS Libraries |
|---------|----------|-------------|----------------------|
| Rails-native ERB | ✅ | ❌ (HTML/React) | ❌ |
| Form Builder | ✅ | ❌ | ❌ |
| Tailwind CSS | ✅ | ✅ | Varies |
| Dark mode | ✅ | ✅ | Varies |
| Rails generators | ✅ | ❌ | ❌ |
| Strict locals | ✅ | ❌ | ❌ |

---

## Best Practices

1. Always use Rails UI component classes before reaching for custom CSS
2. Combine with Tailwind utilities for spacing, sizing, and layout
3. Use semantic color classes (`primary`, `secondary`) over fixed colors for theme consistency
4. Use the form builder for all forms to maintain consistent styling
5. Create reusable partials with strict locals for complex components
6. Icons should use `size-*` classes for consistent sizing
7. Test both light and dark modes