> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Dashboard

> Customize and extend the Spree Admin Dashboard to manage products, orders, customers, promotions, and store settings for your ecommerce platform.

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

![Spree Admin Dashboard](https://mintcdn.com/spreecommerce/cQFxCIv2IPZLev6h/images/spree_admin_dashboard.png?fit=max\&auto=format\&n=cQFxCIv2IPZLev6h\&q=85\&s=effae741cd385f1dd8618eedd326449c)

## 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](https://spreecommerce.org/docs/developer/tutorial/admin.md)**
>
> Create entirely new admin pages for custom features like Brands, Vendors, or any custom model

> **[Extend Existing UI](https://spreecommerce.org/docs/developer/admin/extending-ui.md)**
>
> Inject custom fields, buttons, and sections into existing admin pages

> **[Custom Navigation](https://spreecommerce.org/docs/developer/admin/navigation.md)**
>
> Add menu items to the sidebar or create custom navigation structures

> **[Custom Styling](https://spreecommerce.org/docs/developer/admin/custom-css.md)**
>
> 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

```ruby theme={"theme":"night-owl"}
# 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
```

> [!NOTE]
>
> Learn more about creating admin sections in the [Admin Dashboard Tutorial](https://spreecommerce.org/docs/v5/developer/tutorial/admin.md).

### Views & Templates

Views use standard Rails ERB templates with Spree's [Form Builder](https://spreecommerce.org/docs/v5/developer/admin/form-builder.md) and [Components](https://spreecommerce.org/docs/v5/developer/admin/components.md):

```erb theme={"theme":"night-owl"}
<%# 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](https://hotwire.dev/) (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

```erb theme={"theme":"night-owl"}
<%# Using Stimulus controllers %>
<div data-controller="dropdown">
  <button data-action="dropdown#toggle">Menu</button>
  <div data-dropdown-target="menu">...</div>
</div>
```

> [!NOTE]
>
> Add custom JavaScript using [Stimulus controllers](https://spreecommerce.org/docs/v5/developer/admin/custom-javascript.md).

### Styling

The Admin Dashboard uses [Tailwind CSS v4](https://tailwindcss.com/) for styling. You can:

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

```erb theme={"theme":"night-owl"}
<%# 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>
```

> [!NOTE]
>
> Learn how to customize styles in [Custom CSS](https://spreecommerce.org/docs/v5/developer/admin/custom-css.md).

## Quick Reference

### Available Tools

| Tool | Purpose | Documentation |
| - | - | - |
| Form Builder | Create consistent forms with validation | [Form Builder](https://spreecommerce.org/docs/v5/developer/admin/form-builder.md) |
| Components | Dropdowns, dialogs, icons, badges, etc. | [Components](https://spreecommerce.org/docs/v5/developer/admin/components.md) |
| Helper Methods | Navigation, links, utilities | [Helper Methods](https://spreecommerce.org/docs/v5/developer/admin/helper-methods.md) |
| UI Extensions | Inject content into existing pages | [Extending UI](https://spreecommerce.org/docs/v5/developer/admin/extending-ui.md) |

### 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

```bash Spree CLI (Docker) theme={"theme":"night-owl"}
# 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
```

```bash Without Spree CLI theme={"theme":"night-owl"}
# 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

> [!NOTE]
>
> See [Authentication](https://spreecommerce.org/docs/v5/developer/admin/authentication.md) for setup details.

### Authorization

Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization:

```ruby theme={"theme":"night-owl"}
# Check permissions in controllers
authorize! :update, @product

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

> [!NOTE]
>
> See [Permissions](https://spreecommerce.org/docs/v5/developer/customization/permissions.md) for defining custom abilities.

## Next Steps

> **[Tutorial: Build Admin UI](https://spreecommerce.org/docs/developer/tutorial/admin.md)**
>
> Step-by-step guide to creating a complete admin section

> **[Form Builder](https://spreecommerce.org/docs/developer/admin/form-builder.md)**
>
> Learn all available form field helpers

> **[Components](https://spreecommerce.org/docs/developer/admin/components.md)**
>
> Explore UI components like dropdowns, dialogs, and icons

> **[Extending UI](https://spreecommerce.org/docs/developer/admin/extending-ui.md)**
>
> Add custom content to existing admin pages


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.