Form Builder - Rails UI

Docs

Forms

Rails UI includes a form builder and built-in styles so your forms look consistent with your theme, no matter how you build them.

Railsui::FormBuilder

The Railsui::FormBuilder extends Rails default form builder to automatically apply consistent styling and structure to form elements. It wraps fields with proper labels, error messages, and help text while maintaining Rails conventions.

Basic Usage

To use the Rails UI form builder, specify it in your form:

.html.erb

<%= form_with model: @user, builder: Railsui::FormBuilder do |f| %>
  
  <%= f.text_field :name, label: "Full Name", required: true %>

  <%= f.email_field :email, label: "Email Address", help: "We'll never share your email" %>

  <%= f.password_field :password, label: "Password" %>

  <%= f.submit "Create Account" %>
<% end %>

Available Form Fields

All standard Rails form helpers are enhanced with automatic styling:

.html.erb

<%= form_with model: @model, builder: Railsui::FormBuilder do |form| %>
  <!-- Text inputs -->
  <%= form.text_field :title, label: "Title" %>
  <%= form.email_field :email, label: "Email" %>
  <%= form.password_field :password, label: "Password" %>
  <%= form.number_field :age, label: "Age" %>
  <%= form.telephone_field :phone, label: "Phone" %>
  <%= form.url_field :website, label: "Website" %>
  <%= form.search_field :query, label: "Search" %>

  <!-- Date and time -->
  <%= form.date_field :start_date, label: "Start Date" %>
  <%= form.datetime_field :published_at, label: "Published At" %>
  <%= form.time_field :alarm, label: "Alarm Time" %>

  <!-- Text areas -->
  <%= form.text_area :description, label: "Description", rows: 5 %>
  <%= form.rich_text_area :content, label: "Content" %>

  <!-- Selections -->
  <%= form.select :status, ["Draft", "Published"], {}, label: "Status" %>

  <!-- File uploads -->
  <%= form.file_field :avatar, label: "Avatar" %>

  <!-- Special inputs -->
  <%= form.color_field :theme_color, label: "Theme Color" %>
  <%= form.range_field :volume, label: "Volume", min: 0, max: 100 %>
<% end %>

Checkboxes and Radio Buttons

Checkboxes and radio buttons include automatic label alignment:

.html.erb

<%= form_with model: @model, builder: Railsui::FormBuilder do |form| %>
  <!-- Single checkbox with inline label -->
  <%= form.check_box :terms, label: "I agree to the terms", required: true %>

  <!-- Radio buttons with labels -->
  <%= form.radio_button :plan, "free", label: "Free Plan" %>
  <%= form.radio_button :plan, "pro", label: "Pro Plan" %>
  <%= form.radio_button :plan, "enterprise", label: "Enterprise Plan" %>

  <!-- Switch field (styled checkbox) -->
  <%= form.switch_field :notifications, label: "Email notifications" %>
<% end %>

Form Options

Each field supports additional options for customization:

.html.erb

<%= form.text_field :username,
  label: "Username",
  help: "Choose a unique username",
  placeholder: "johndoe",
  required: true,
  class: "custom-class",
  # default class for wrapper is "form-group"
  # drop wrapper entirely -> wrapper: false
  wrapper: { class: "mb-8" }, 
  label_options: { class: "text-lg" } %>

Available Options

label - Field label text (set to false to skip)
help - Help text displayed below the field
required - Marks field as required with visual indicator
wrapper - HTML attributes for the field wrapper div. Use wrapper: false to forego a wrapper.
label_options - HTML attributes for the label element
skip_label - Omits the label entirely when true
placeholder - Standard HTML placeholder attribute
class - Additional CSS classes for the input

Error Handling

Form fields automatically display validation errors from your models:

# app/models/user.rb
class User < ApplicationRecord
  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
  validates :name, presence: true, length: { minimum: 2 }
end

When validation fails, fields automatically:

Apply error styling (red border and text)
Display error messages below the field
Add the form-input-error class

Form Helpers

Additional helper methods for form structure:

.html.erb

<%= form_with model: @model, builder: Railsui::FormBuilder do |form| %>
  <!-- Form groups for custom layouts and default offsets -->
  <%= form.form_group class: "grid grid-cols-2 gap-4" do %>
    <%= form.text_field :first_name, label: "First Name", wrapper: false %>
    <%= form.text_field :last_name, label: "Last Name", wrapper: false %>
  <% end %>

  <!-- Standalone help text -->
  <%= form.form_help "Fields marked with * are required", class: "mb-4" %>

  <!-- Custom error messages -->
  <%= form.error_message(:email) if @model.errors[:email].any? %>
<% end %>

Using Standard Rails Forms

If you prefer standard Rails form helpers, apply the CSS classes directly:

.html.erb

<%= form_with model: @user do |form| %>
  <div class="form-group">
    <%= form.label :email, class: "form-label" %>
    <%= form.email_field :email, class: "form-input", placeholder: "[email protected]" %>
    <p class="form-help">We'll never share your email</p>
  </div>

  <div class="form-group">
    <%= form.label :bio, class: "form-label" %>
    <%= form.text_area :bio, class: "form-textarea", rows: 4 %>
  </div>

  <div class="form-group">
    <%= form.label :role, class: "form-label" %>
    <%= form.select :role, ["Admin", "User"], {}, class: "form-select" %>
  </div>

  <div class="flex items-center gap-2">
    <%= form.check_box :subscribe, class: "form-input-checkbox" %>
    <%= form.label :subscribe, "Subscribe to newsletter", class: "form-label mb-0" %>
  </div>

  <%= form.submit "Save", class: "btn btn-primary" %>
<% end %>

CSS Classes Reference

Rails UI provides a comprehensive set of form CSS classes for consistent styling:

Basic Input Classes

Class	Usage
`form-group`	Wrapper for form field groups. Appends by default unless `wrapper: false` is set.
`form-label`	Label styling
`form-label-required`	Required field indicator
`form-input`	Text input, email, password, etc.
`form-textarea`	Textarea styling
`form-select`	Select dropdown styling
`form-help`	Help text below fields
`form-input-error`	Error state styling

Special Input Classes

Class	Usage
`form-input-checkbox`	Checkbox styling
`form-input-radio`	Radio button styling
`form-input-switch`	Toggle switch (styled checkbox)
`form-input-range`	Range slider with fill indicator
`form-input-color`	Color picker styling
`form-file`	File upload styling

Variants and Modifiers

Class	Usage
`form-input-sm`	Smaller input size
`form-select-minimal`	Borderless select
`form-select-sort`	Sort dropdown styling

Complex Form Examples

Registration Form

.html.erb

<%= form_with model: @user, builder: Railsui::FormBuilder do |form| %>
  <div class="grid md:grid-cols-2 gap-4">
    <%= form.text_field :first_name, label: "First Name", required: true, wrapper: false %>
    <%= form.text_field :last_name, label: "Last Name", required: true, wrapper: false %>
  </div>

  <%= form.email_field :email,
    label: "Email Address",
    required: true,
    help: "Use your work email for faster approval" %>

  <%= form.password_field :password,
    label: "Password",
    required: true,
    help: "Minimum 8 characters" %>

  <%= form.select :role,
    options_for_select([
      ["Developer", "developer"],
      ["Designer", "designer"],
      ["Manager", "manager"]
    ]),
    { prompt: "Select your role" },
    label: "Role" %>

  <%= form.check_box :terms,
    label: "I agree to the Terms of Service",
    required: true %>

  <%= form.switch_field :newsletter,
    label: "Subscribe to product updates" %>

  <div class="flex gap-3 mt-6">
    <%= form.submit "Create Account", class: "btn btn-primary" %>
    <%= link_to "Cancel", root_path, class: "btn btn-white" %>
  </div>
<% end %>

Accessibility

The form builder automatically includes accessibility features:

Proper label-input association using for attributes
Required field indicators with semantic markup
ARIA attributes for error states
Keyboard navigation support
Focus states for all interactive elements
Screen reader-friendly error messages

Dark Mode Support

All form elements include dark mode variants that automatically adapt to your theme settings. The styles use Tailwind's dark mode utilities for seamless theme switching.

JavaScript Integration

Some form elements require JavaScript for enhanced functionality:

Range fields - Uses railsui-range Stimulus controller for fill indicator
Rich text areas - Integrates with ActionText/Trix editor
File uploads - Can integrate with Active Storage direct uploads

These controllers are included with the railsui-stimulus package that comes with Rails UI.

Forms

Railsui::FormBuilder

Basic Usage

Available Form Fields

Checkboxes and Radio Buttons

Form Options

Available Options

Error Handling

Form Helpers

Using Standard Rails Forms

CSS Classes Reference

Basic Input Classes

Special Input Classes

Variants and Modifiers

Complex Form Examples

Registration Form

Accessibility

Dark Mode Support

JavaScript Integration

On this page

Get all updates directly to your inbox.
Sign up for the newsletter.

Forms

Railsui::FormBuilder

Basic Usage

Available Form Fields

Checkboxes and Radio Buttons

Form Options

Available Options

Error Handling

Form Helpers

Using Standard Rails Forms

CSS Classes Reference

Basic Input Classes

Special Input Classes

Variants and Modifiers

Complex Form Examples

Registration Form

Accessibility

Dark Mode Support

JavaScript Integration

On this page

Get all updates directly to your inbox. Sign up for the newsletter.

Get all updates directly to your inbox.
Sign up for the newsletter.