Getting Started - Rails UI Components

Requirements

Ruby 3.2.3+
Rails 7.0.8+
ViewComponent gem

Node.js 18+
Vite for asset compilation

Installation

1. Add Required Gems

Add these dependencies to your Gemfile:

# Gemfile
gem 'view_component'
gem 'vite_rails'
gem 'turbo-rails'

# Below are optional just for enhanced functionality
gem 'pagy', '~> 9.3.4' # For pagination
gem 'gretel' # For breadcrumbs
gem 'meta-tags' # For SEO meta tags
gem 'inline_svg'  # For SVG icons
gem 'image_processing', '~> 1.2' # For image uploads
gem 'shrine', '~> 3.0' # For file uploads

2. Add Required Frontend Dependencies

Add dependencies you need to your Package.json:

# Package.json
"dependencies": {
  "@hotwired/stimulus": "^3.2.2",
  "@hotwired/turbo-rails": "^8.0.2",
  "flowbite": "^3.1.2", // JS libraries from Flowbite
  "@easepick/bundle": "^1.2.1", // Datepicker library
  "@rails/request.js": "^0.0.9", // Rails AJAX helper
  "choices.js": "^11.1.0", // Custom select library
  "imask": "^7.6.1", // Input masking library
  "mjml": "^4.15.3", // MJML email templates
  "stimulus-rails-autosave": "^5.1.0", // Autosave form data
  "stimulus-textarea-autogrow": "^4.1.0", // Auto-grow textarea
  "stimulus-use": "^0.52.2", // Reusable Stimulus behaviors
},
"devDependencies": {
  "@tailwindcss/forms": "^0.5.10", // TailwindCSS forms plugin
  "@tailwindcss/typography": "^0.5.18", // TailwindCSS typography plugin
  "@tailwindcss/vite": "^4.0.6", // TailwindCSS Vite plugin
  "standard": "^17.1.0",
  "stimulus-vite-helpers": "^3.1.0",
  "tailwindcss": "^4.0.6",
  "vite": "^7.1.7",
  "vite-plugin-rails": "^0.5.0"
}

3. Install Dependencies

# Install Ruby gems
bundle install

# Install frontend dependencies
yarn install

4. Copy Components

It's better to have 100% the same structure as in this template app.

This ensures all dependencies and configurations are correctly set up.

But you can copy only what you need from this template to your Rails project:

📁 Copy app/components/ui/ folder or individual component folders to your project.

📁 Copy app/assets/controllers/ folder or individual Stimulus controllers to your project.

📁 Copy app/assets/stylesheets/components/ui/ folder for component-specific styles.

5. Start Development

# Start Rails server
bin/rails server

# Start Vite dev server (in another terminal)
yarn dev

We recommend using Overmind

Overmind is a great tool for managing your development environment. We have `Procfile.dev` set up for you.

Component Structure

Each component follows a consistent pattern:

app/components/ui/[component_name]/
├── component.rb          # Main component class
├── component.html.erb    # Template (when needed)
├── component.css         # Component-specific styles
├── component_controller.js # Stimulus controller (when needed)
└── [nested_components]/  # Sub-components

💡 Tip

All components inherit from ApplicationComponent and are namespaced under Ui::

What's Next?

Now that you have the basics, explore individual components in the sidebar to see detailed examples and learn about their specific options and usage patterns.

Don't forget to check out Good to know for architectural insights and best practices.