Customization

Three Approaches to Customization

RapidRails UI gives you multiple levels of customization control, depending on your needs:

Approach 1: Tailwind Classes

The fastest way to customize a component is by passing additional Tailwind classes.

Adding Spacing and Layout

All RapidRails UI components accept a class option for custom classes:

// Add margin, width, custom styles
<%= rui_button("Save", color: :secondary, class: "mt-4 w-full") %>

// Override background color
<%= rui_button("Custom", class: "bg-gradient-to-r from-purple-500 to-pink-500 w-sm") %>

// Add shadow and animation
<%= rui_button("Fancy", color: :orange, class: "shadow-lg hover:scale-105 transition-transform") %>

How Class Merging Works

RapidRails UI uses intelligent class merging. When you pass custom classes:

• Additive classes (like mt-4, w-full) are simply added
• Conflicting classes (like bg-*) override the component's defaults
• Classes are merged in a way that respects Tailwind's specificity

Approach 2: Copy & Edit Components

For full control, use the component generator to copy any component into your application and modify it.

List Available Components

First, see which components you can copy:

rails g rapid_rails_ui:component --list

This will show all available components with descriptions.

Copy Components to Your App

Use the generator to copy one or more components:

rails g rapid_rails_ui:component button

rails g rapid_rails_ui:component icon social_button

📦 Copying button component to your app...
   ✅ button copied to app/components/rapid_rails_ui/button/
   📝 You can now customize this component!

The generator will copy the entire component directory to app/components/rapid_rails_ui/<component_name>/

Customize the Component

After copying, you can modify any file in the component directory:

app/components/rapid_rails_ui/button/
├── component.rb           
├── component.html.erb     
└── styles.rb             

Edit any of these files to customize the component's behavior, structure, or styles.

Component Loading Priority

Rails automatically prefers your local copy over the gem version:

• 1st priority: app/components/rapid_rails_ui/ (your custom version)
• 2nd priority: Gem's app/components/rapid_rails_ui/ (default)

Approach 3: Global Configuration

Configure default colors, sizes, and options globally in the RapidRails UI initializer.

Setting Up the Initializer

The installer creates config/initializers/rapid_rails_ui.rb for you:

# config/initializers/rapid_rails_ui.rb
RapidRailsUI.configure do |config|
  # Default color for all buttons
  config.button_color = :blue

  # Default size for all buttons
  config.button_size = :md

  # Default variant for all buttons
  config.button_variant = :solid

  # Icon size defaults
  config.icon_size = :md
end

Custom Color Palettes

Define custom semantic colors for your brand:

# config/initializers/rapid_rails_ui.rb
RapidRailsUI.configure do |config|
  # Override the 'primary' color
  config.colors[:primary] = {
    base: "indigo-600",
    hover: "indigo-700",
    active: "indigo-800",
    text: "white"
  }

  # Add a custom semantic color
  config.colors[:brand] = {
    base: "purple-600",
    hover: "purple-700",
    active: "purple-800",
    text: "white"
  }
end

Now you can use your custom colors:

<%= rui_button("Brand Button", color: :brand) %>

Size Customization

Customize the size scale globally:

# config/initializers/rapid_rails_ui.rb
RapidRailsUI.configure do |config|
  config.sizes[:button] = {
    xs: "px-2 py-1 text-xs",
    sm: "px-3 py-2 text-sm",
    md: "px-4 py-3 text-base",    # Larger default medium
    lg: "px-6 py-4 text-lg",      # Larger large
    xl: "px-8 py-5 text-xl"       # New extra-large size
  }
end