IronAdmin

Convention-over-configuration admin panel engine for Ruby on Rails. Build beautiful admin interfaces with minimal code.

Live demo · Demo source · Documentation · What's new in 0.7

The demo is Meridian Magazine, a Rails 8 app built with IronAdmin. Sign in as one of three users (an admin, an editor or an author; no password needed) and see how resource policies change what each role can do. Its source has the resources, dashboard, policies and theme behind it.

Features

• Zero Configuration CRUD - Auto-generates forms and tables from your database schema
• Resource DSL - Customize fields, filters, scopes, and actions with a clean Ruby DSL
• Dashboard Builder - Create metrics, charts, and recent records widgets
• Themes - A minimal default look (Neutral), named themes such as a dark one, and a theme switcher in the navbar; every color, font, radius and shadow is a Tailwind class you can change
• Authorization - Built-in policy system for fine-grained access control
• Search - Global search across all resources
• Export - CSV and JSON export out of the box

Requirements

• Ruby >= 3.3 (tested on 3.3, 3.4, and 4.0)
• Rails >= 8.0.4 (tested on 8.0 and 8.1)
• tailwindcss-rails >= 4.3
• The default rails new JavaScript setup: importmap with Stimulus. IronAdmin installs importmap-rails itself; its layout loads the admin JavaScript with javascript_importmap_tags and registers its Stimulus controllers on window.Stimulus, which bin/rails stimulus:install sets up.

Installation

Add to your Gemfile:

gem "iron_admin"
gem "tailwindcss-rails"

Then run:

bundle install
rails generate iron_admin:install

The install generator will:

• Create app/iron_admin/resources/ and app/iron_admin/dashboards/ directories
• Add a configuration initializer at config/initializers/iron_admin.rb
• Create a sample dashboard
• Mount the engine at /admin in your routes
• Add the IronAdmin Tailwind CSS import to your app/assets/tailwind/application.css

Tailwind CSS Setup

IronAdmin uses Tailwind CSS v4 for all styling. The tailwindcss-rails gem handles compilation. After running the install generator, your app/assets/tailwind/application.css should include:

@import "tailwindcss";
@import "../builds/tailwind/iron_admin";

The second line imports IronAdmin's @source directives so the Tailwind compiler scans the engine's views and components for CSS classes. Without it, the admin panel will render unstyled.

If you're setting up manually (without the generator), run:

rails tailwindcss:build

Then verify that app/assets/builds/tailwind/iron_admin.css was created. If not, check that tailwindcss-rails >= 4.3 is installed (4.3 added the tailwindcss:engines task that writes this file) and that the engine gem is properly loaded.

For development, use bin/dev or rails tailwindcss:watch to recompile CSS on changes.

Quick Start

1. Configure Authentication

# config/initializers/iron_admin.rb
IronAdmin.configure do |config|
  config.title = "My App Admin"

  config.authenticate do |controller|
    user = User.find_by(id: controller.session[:user_id])
    controller.redirect_to "/login" unless user&.admin?
  end

  config.current_user do |controller|
    User.find_by(id: controller.session[:user_id])
  end
end

An app built with bin/rails generate authentication does not store the user id in session[:user_id]. IronAdmin controllers inherit from ActionController::Base, so the host's Authentication concern and Current.user are not available in this block. Use the Rails 8 authentication generator example.

2. Generate Resources

rails generate iron_admin:resource User
rails generate iron_admin:resource Product
rails generate iron_admin:resource Order

3. Customize Resources

# app/iron_admin/resources/user_resource.rb
module IronAdmin
  module Resources
    class UserResource < IronAdmin::Resource
      field :role, type: :badge, colors: { admin: :purple, user: :blue }
      field :email, type: :text

      searchable :name, :email

      filter :role, type: :select, options: User.roles.keys
      filter :created_at, type: :date_range

      scope :admins, -> { where(role: :admin) }
      scope :recent, -> { where("created_at > ?", 7.days.ago) }

      index_fields :id, :name, :email, :role, :created_at
      form_fields :name, :email, :role

      menu priority: 1, icon: "users", group: "People"

      action :lock, icon: "lock-closed", confirm: true do |record|
        record.update!(locked_at: Time.current)
      end
    end
  end
end

4. Create a Dashboard

# app/iron_admin/dashboards/admin_dashboard.rb
module IronAdmin
  module Dashboards
    class AdminDashboard < IronAdmin::Dashboard
      metric :total_users, format: :number do
        User.count
      end

      metric :monthly_revenue, format: :currency do
        Payment.where("created_at > ?", 30.days.ago).sum(:amount)
      end

      recent :users, limit: 5, scope: -> { order(created_at: :desc) }
      recent :payments, limit: 5
    end
  end
end

Visit /admin and your admin panel is ready!

Themes

The four themes of the Meridian Magazine demo. The Theming Guide shows how to build your own.

The default look, Neutral, is a minimal light theme: zinc grays, white surfaces with 1px borders, the Inter typeface, a black primary button and an indigo accent. Change any of its properties, or register more themes. With two or more, the navbar shows a theme switcher that remembers each person's choice in a cookie:

# config/initializers/iron_admin.rb
IronAdmin.configure do |config|
  config.theme do |t| # the default theme
    t.btn_primary = "bg-emerald-700 text-white hover:bg-emerald-600 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-emerald-600"
  end

  config.register_theme(:midnight, label: "Midnight") do |t|
    t.color_scheme = "dark"
    t.main_bg = "bg-zinc-950"
    t.card_bg = "bg-zinc-900"
    # ... every property is listed in the theming guide
  end
end

config.theme_resolver can pick the theme per user or per tenant, and your own components read the request's theme with IronAdmin.current_theme. Neutral loads Inter from Google Fonts; set font_stylesheet_url to nil to turn that request off. See the Theming Guide, which includes a complete dark theme.

Documentation

Full documentation is available at https://rubylab-app.github.io/iron_admin/ and in the docs directory:

• Installation
• Quick Start
• Resources Guide
• Dashboard Guide
• Theming Guide
• Configuration Reference
• Upgrade Guide

Development

After checking out the repo (use the Ruby in .ruby-version; IronAdmin needs Ruby >= 3.3):

bundle install
bundle exec rspec
bundle exec rubocop . .github/scripts

Contributing

See CONTRIBUTING.md for details.

License

The gem is available as open source under the terms of the MIT License.