Skip to main content
Spree Admin Dashboard uses Tailwind CSS v4 for styling. The stylesheet system is designed to be easily customizable while maintaining consistency with the Spree design system.

​
How It Works

When you install Spree Admin, the installer creates a file at app/assets/tailwind/spree_admin.css in your application. This file:
  1. Imports the base Spree Admin styles from the gem
  2. Scans your custom admin views, helpers, and JavaScript for Tailwind classes
  3. Allows you to add custom styles and override theme variables

​
Using Tailwind Utility Classes

You can use any Tailwind CSS utility class in your custom admin views, helpers, or JavaScript files. The build process automatically scans these locations:
  • app/views/spree/admin/**/*.erb
  • app/helpers/spree/admin/**/*.rb
  • app/javascript/spree/admin/**/*.js
Example usage in a view: 
<div class="bg-zinc-100 p-4 rounded-lg shadow-sm">
  <h2 class="text-lg font-bold text-zinc-900">Custom Section</h2>
  <p class="text-sm text-zinc-600 mt-2">Your content here</p>
</div>

​
Customizing the Theme

​
Overriding Theme Colors

To override Tailwind theme values, add a @theme block in your app/assets/tailwind/spree_admin.css file after the import:
app/assets/tailwind/spree_admin.css
/* Import Spree Admin base styles from the gem */
@import "$SPREE_ADMIN_PATH/app/assets/tailwind/spree/admin/index.css";

/* Override theme colors */
@theme {
  --color-primary: #4F46E5;      /* Change primary color to indigo */
  --color-success: #059669;      /* Custom success color */
  --color-danger: #DC2626;       /* Custom danger color */
}

​
Available Theme Variables

The Spree Admin theme defines these customizable variables:
VariableDefaultDescription
--color-primaryvar(--color-zinc-950)Primary brand color
--color-successvar(--color-green-900)Success state color
--color-dangervar(--color-red-600)Error/danger state color
--color-warningvar(--color-yellow-900)Warning state color
--color-infovar(--color-blue-900)Info state color

​
Overriding Layout Variables

You can also customize layout-related CSS variables:
app/assets/tailwind/spree_admin.css
:root {
  --spacing-sidebar-width: 280px;      /* Default: 220px */
  --spacing-sidebar-collapsed: 70px;   /* Default: 59px */
  --spacing-header-height: 64px;       /* Default: 58px */
}

​
Adding Custom Components

Use Tailwind’s @layer directive to add custom component styles that work seamlessly with the existing design:
app/assets/tailwind/spree_admin.css
@layer components {
  /* Custom card style */
  .my-custom-card {
    @apply bg-white rounded-lg shadow-sm border border-zinc-200 p-4;
  }

  /* Custom button variant */
  .btn-custom {
    @apply inline-flex items-center px-4 py-2 rounded-md;
    @apply bg-indigo-600 text-white font-medium;
    @apply hover:bg-indigo-700 transition-colors;
  }

  /* Custom status badge */
  .status-badge {
    @apply inline-flex items-center px-2 py-1 rounded-full text-xs font-medium;
  }

  .status-badge-active {
    @apply status-badge bg-green-100 text-green-800;
  }

  .status-badge-inactive {
    @apply status-badge bg-zinc-100 text-zinc-600;
  }
}

​
Adding Custom Utilities

For reusable utility classes, use the utilities layer:
app/assets/tailwind/spree_admin.css
@layer utilities {
  .text-gradient {
    @apply bg-clip-text text-transparent bg-gradient-to-r from-indigo-500 to-purple-500;
  }

  .scrollbar-hidden {
    -ms-overflow-style: none;
    scrollbar-width: none;
  }

  .scrollbar-hidden::-webkit-scrollbar {
    display: none;
  }
}

​
Scanning Additional Paths

If you have admin-related code in non-standard locations, add additional @source directives:
app/assets/tailwind/spree_admin.css
/* Scan host app's custom admin code for Tailwind classes */
@source "../../views/spree/admin/**/*.erb";
@source "../../helpers/spree/admin/**/*.rb";
@source "../../javascript/spree/admin/**/*.js";

/* Add your custom paths */
@source "../../components/admin/**/*.erb";
@source "../../views/admin/**/*.erb";

​
Development Workflow

​
Starting the CSS Watcher

During development, run the Tailwind CSS watcher to automatically rebuild styles when you make changes: 
bin/rails spree:admin:tailwindcss:watch
Or if you’re using Procfile.dev with foreman: 
bin/dev
The watcher monitors:
  • Your host app’s CSS files in app/assets/tailwind/
  • The Spree Admin engine’s CSS files
  • All files matching your @source patterns

​
Building for Production

CSS is automatically compiled during asset precompilation: 
bin/rails assets:precompile

​
Common Customization Examples

​
Custom Primary Color Scheme

app/assets/tailwind/spree_admin.css
@theme {
  /* Use blue as the primary color */
  --color-primary: #2563EB;
}

@layer components {
  /* Ensure buttons use the new primary color */
  .btn-primary {
    @apply bg-blue-600 hover:bg-blue-700;
  }
}

​
Dark Mode Adjustments

app/assets/tailwind/spree_admin.css
@layer base {
  /* Custom dark mode overrides */
  .dark {
    --color-primary: #60A5FA;
  }
}

​
Custom Form Styling

app/assets/tailwind/spree_admin.css
@layer components {
  /* Custom input style */
  .input-custom {
    @apply block w-full rounded-md border-zinc-300 shadow-sm;
    @apply focus:border-indigo-500 focus:ring-indigo-500;
  }

  /* Custom select style */
  .select-custom {
    @apply block w-full rounded-md border-zinc-300 py-2 pl-3 pr-10;
    @apply focus:border-indigo-500 focus:outline-none focus:ring-indigo-500;
  }
}

​
Troubleshooting

​
Changes Not Appearing

  1. Ensure the watcher is running: bin/rails spree:admin:tailwindcss:watch
  2. Check that your files are in paths covered by @source directives
  3. Hard refresh the browser (Cmd+Shift+R or Ctrl+Shift+R)

​
Missing Utility Classes

If a Tailwind class isn’t working, ensure:
  1. The class is used in a file that’s scanned by @source
  2. The class name is complete (not dynamically constructed)
  3. Run a fresh build: bin/rails spree:admin:tailwindcss:build

​
Listen Gem Required

The watch task requires the listen gem. Add it to your Gemfile:
Gemfile
group :development do
  gem 'listen', '>= 3.0'
end