Configuration

Initializer Setup

The RapidRails UI installer creates an initializer file at config/initializers/rapid_rails_ui.rb. This is where you configure global defaults for your application.

Basic Structure

RapidRailsUI.configure do |config|
  # Configurable semantic colors (map each to any Tailwind family)
  config.colors = { primary: "blue", secondary: "sky", tertiary: "indigo", accent: "violet" }

  # Per-component default options
  config.defaults = {
    button: { variant: :solid, size: :base, color: :primary },
    icon:   { size: :sm, color: :current }
  }

  # Namespace the gem's Stimulus controllers (optional, v0.47.0+)
  # config.stimulus_namespace = "rui"
end

Color System

RapidRails UI supports 22 Tailwind colors plus semantic color names.

Available Colors

You can use any of these colors with the color: option:

Customizing Semantic Colors

Map the four configurable semantic colors to any Tailwind color family to match your brand. Each value is a Tailwind color name (a built-in family or a custom palette you define in your Tailwind config). Components resolve the right shades automatically and emit dark-mode variants for you.

RapidRailsUI.configure do |config|
  config.colors = {
    primary:   "midnight",   # any Tailwind family: blue, zinc, purple, or a custom palette
    secondary: "clay",
    tertiary:  "cream",
    accent:    "brand_sky"
  }
end

Dark Mode

Dark mode is automatic. Components emit Tailwind dark: variants for every color (for example lighter text and border shades), so a configured palette adapts to dark mode with no extra color configuration. See the Dark Mode guide for how to enable dark mode in your app.

Size System

RapidRails UI provides a consistent size scale across all components.

Default Size Options

All components support these size options:

Setting a Default Size

Size is chosen per call with the size: option. To change a component's default size app-wide, set it under config.defaults:

RapidRailsUI.configure do |config|
  config.defaults = {
    button: { size: :lg },
    icon:   { size: :base }
  }
end

Component Defaults

Set default options for each component type.

config.defaults is a hash keyed by component; each value is that component's default options. Set the components you want to change.

RapidRailsUI.configure do |config|
  config.defaults = {
    button: { variant: :solid, size: :base, shape: :rounded, color: :primary },
    badge:  { variant: :solid, size: :sm, color: :primary },
    icon:   { size: :sm, color: :current }
  }
end

Available Variants

Most components support these variants:

Icon Configuration

Configure default behavior for icons across your application.

Icon Defaults

RapidRailsUI.configure do |config|
  config.defaults = {
    icon: { size: :sm, color: :current }  # :current inherits the surrounding text color
  }
end

RapidRails UI includes 1500+ Lucide icons. Find all available icons at: lucide.dev/icons

Stimulus Namespace

Available in v0.47.0+. Opt-in option that prefixes every Stimulus identifier the gem emits (data-controller, data-action, data-X-target, data-X-Y-value) so the gem's controllers coexist with host-app controllers of the same name without collision.

RapidRailsUI.configure do |config|
  config.stimulus_namespace = "rui"
end

Full guide (emitted HTML, JS registration, custom triggers, helpers, troubleshooting): Stimulus Namespace →

Quick Reference

Complete configuration reference with all available options:

RapidRailsUI.configure do |config|
  # === Configurable Semantic Colors (optional) ===
  # Map :primary/:secondary/:tertiary/:accent to any Tailwind color family.
  # Status colors (:success, :danger, :warning, :info) are fixed by convention.
  config.colors = {
    primary:   "blue",     # default: "zinc"
    secondary: "sky",      # default: "sky"
    tertiary:  "indigo",   # default: "indigo"
    accent:    "violet"    # default: "violet"
  }

  # === Per-component Defaults (optional) ===
  # Hash keyed by component; each value is that component's default options.
  config.defaults = {
    button: { variant: :solid, size: :base, shape: :rounded, color: :primary },
    badge:  { variant: :solid, size: :sm, shape: :rounded, color: :primary },
    icon:   { size: :sm, color: :current },
    card:   { shape: :rounded, shadow: :md }
  }

  # === Stimulus Namespace (optional, v0.47.0+) ===
  config.stimulus_namespace = "rui"   # default: nil. See "Stimulus Namespace" above.
end