Admin Dashboard

The Spree Admin Dashboard is a full-featured administration interface for managing your e-commerce store.

What You Can Do

The Admin Dashboard allows store administrators to manage:

Products - Create and manage products, variants, images, and inventory
Orders - Process orders, refunds, and shipments
Customers - View customer accounts and order history
Promotions - Create discounts, coupon codes, and special offers
Settings - Configure store settings, shipping, taxes, and payments

Customization Options

As a developer, you can fully customize the Admin Dashboard:

Add New Sections

Create entirely new admin pages for custom features like Brands, Vendors, or any custom model

Extend Existing UI

Inject custom fields, buttons, and sections into existing admin pages

Custom Navigation

Add menu items to the sidebar or create custom navigation structures

Custom Styling

Add your own CSS to match your brand or modify the look and feel

Architecture Overview

Spree Admin follows standard Rails conventions with some Spree-specific patterns:

app/
├── controllers/
│   └── spree/
│       └── admin/
│           └── products_controller.rb    # Your custom controllers
├── views/
│   └── spree/
│       └── admin/
│           └── products/
│               ├── index.html.erb        # List view
│               ├── _form.html.erb        # Shared form partial
│               └── _table_row.html.erb   # Table row partial
├── helpers/
│   └── spree/
│       └── admin/
│           └── products_helper.rb        # View helpers
└── assets/
    └── tailwind/
        └── spree_admin.css               # Custom Tailwind styles

Key Concepts

Controllers

Admin controllers inherit from Spree::Admin::ResourceController which provides:

Full CRUD operations (index, new, create, edit, update, destroy)
Automatic authorization checks
Flash messages and redirects
Search and filtering with Ransack

# app/controllers/spree/admin/brands_controller.rb
module Spree
  module Admin
    class BrandsController < ResourceController
      # That's it! CRUD is handled automatically.
      # Override methods only when needed.
    end
  end
end

Learn more about creating admin sections in the Admin Dashboard Tutorial.

Views & Templates

Views use standard Rails ERB templates with Spree’s Form Builder and Components:

<%# app/views/spree/admin/brands/_form.html.erb %>
<div class="card mb-6">
  <div class="card-header">
    <h5 class="card-title"><%= Spree.t(:general_settings) %></h5>
  </div>
  <div class="card-body">
    <%= f.spree_text_field :name, required: true %>
    <%= f.spree_text_area :description %>
    <%= f.spree_file_field :logo, width: 300, height: 300 %>
    <%= f.spree_check_box :active %>
  </div>
</div>

JavaScript & Interactivity

Spree Admin uses Hotwire (Turbo + Stimulus) for interactivity:

Turbo Drive - Fast page navigation without full reloads
Turbo Frames - Update parts of the page independently
Turbo Streams - Real-time updates over WebSocket
Stimulus - Lightweight JavaScript controllers

<%# Using Stimulus controllers %>
<div data-controller="dropdown">
  <button data-action="dropdown#toggle">Menu</button>
  <div data-dropdown-target="menu">...</div>
</div>

Add custom JavaScript using Stimulus controllers.

Styling

The Admin Dashboard uses Tailwind CSS v4 for styling. You can:

Use Tailwind utility classes directly in your views
Override theme variables (colors, spacing, typography)
Add custom components using @layer components

<%# Using Tailwind utility classes in views %>
<div class="bg-white rounded-lg shadow-sm border border-zinc-200 p-4">
  <h3 class="text-lg font-bold text-zinc-900">My Custom Card</h3>
  <p class="text-sm text-zinc-600 mt-2">Card content here</p>
</div>

Learn how to customize styles in Custom CSS.

Quick Reference

Available Tools

Tool	Purpose	Documentation
Form Builder	Create consistent forms with validation	Form Builder
Components	Dropdowns, dialogs, icons, badges, etc.	Components
Helper Methods	Navigation, links, utilities	Helper Methods
UI Extensions	Inject content into existing pages	Extending UI

Common Tasks

Task	How To
Add a new admin page	Use the scaffold generator: `bin/rails g spree:admin:scaffold Spree::Brand`
Add sidebar navigation	Use `Spree.admin.navigation.sidebar.add` in an initializer
Add form fields	Use `f.spree_text_field`, `f.spree_select`, etc.
Show flash messages	They’re automatic with `ResourceController`
Check permissions	Use `can?(:update, @product)` in views

Generator Commands

# Generate a complete admin section (controller, views, routes)
spree generate spree:admin:scaffold Spree::Brand

# Generate just a controller
spree generate controller Spree::Admin::Brands --skip-routes

# Generate a complete admin section (controller, views, routes)
bin/rails g spree:admin:scaffold Spree::Brand

# Generate just a controller
bin/rails g controller Spree::Admin::Brands --skip-routes

Authentication & Authorization

Authentication

Admin users must be authenticated to access the dashboard. Spree supports:

Built-in Devise authentication
Custom authentication adapters
SSO integration

See Authentication for setup details.

Authorization

Spree uses CanCanCan for authorization:

# Check permissions in controllers
authorize! :update, @product

# Check permissions in views
<% if can?(:destroy, @product) %>
  <%= link_to_delete(@product) %>
<% end %>

See Permissions for defining custom abilities.

Next Steps

Tutorial: Build Admin UI

Step-by-step guide to creating a complete admin section

Form Builder

Learn all available form field helpers

Components

Explore UI components like dropdowns, dialogs, and icons

Extending UI

Add custom content to existing admin pages

Tutorial

Admin Panel

Customization Reference

What You Can Do

Customization Options

Add New Sections

Extend Existing UI

Custom Navigation

Custom Styling

Architecture Overview

Key Concepts

Controllers

Views & Templates

JavaScript & Interactivity

Styling

Quick Reference

Available Tools

Common Tasks

Generator Commands

Authentication & Authorization

Authentication

Authorization

Next Steps

Tutorial: Build Admin UI

Form Builder

Components

Extending UI

​What You Can Do

​Customization Options

Add New Sections

Extend Existing UI

Custom Navigation

Custom Styling

​Architecture Overview

​Key Concepts

​Controllers

​Views & Templates

​JavaScript & Interactivity

​Styling

​Quick Reference

​Available Tools

​Common Tasks

​Generator Commands

​Authentication & Authorization

​Authentication

​Authorization

​Next Steps

Tutorial: Build Admin UI

Form Builder

Components

Extending UI

What You Can Do

Customization Options

Architecture Overview

Key Concepts

Controllers

Views & Templates

JavaScript & Interactivity

Styling

Quick Reference

Available Tools

Common Tasks

Generator Commands

Authentication & Authorization

Authentication

Authorization

Next Steps