ContextQMD
Back to Spree

Custom CSS for Spree Storefront

docs/developer/storefront/rails/custom-css.mdx

5.4.26.1 KB
Original Source

Spree Storefront is built on top of Tailwind CSS 4. After installing Spree you should find a main CSS file:

If you're missing this file, or migrating from a previous version of Spree, you can generate it using the following command:

bash
bin/rails g spree:storefront:install
<Info> Tailwind 4 uses a CSS-first configuration approach. There's no `tailwind.config.js` file - all configuration is done directly in CSS using the `@theme` directive. </Info>

Basic Structure

Your application.css file should look something like this:

css
@import "tailwindcss";

@theme {
  /* Theme customizations go here */
}

/* Your custom styles */

Importing Additional CSS Files

Create a new CSS file in the app/assets/stylesheets directory:

bash
touch app/assets/tailwind/my_custom_styles.css

In the my_custom_styles.css file, add your styles:

css
.my-custom-class {
  color: red;
}

Then import it in your application.css file:

css
@import "tailwindcss";
@import "my_custom_styles.css"; /* [!code ++] */

Importing 3rd Party CSS Libraries

You can import a 3rd party CSS library directly from a CDN:

css
@import "tailwindcss";
@import url("https://esm.sh/[email protected]/swiper-bundle.min.css"); /* [!code ++] */

CSS Variables

Spree Storefront uses CSS variables that are automatically injected into the page. This allows store owners to change colors, fonts, etc. from the admin dashboard via Page Builder.

The default variables look like this:

css
:root {
  --primary: #000000;
  --accent: #F0EFE9;
  --danger: #C73528;
  --success: #00C773;
  --neutral: #999999;

  --background: #FFFFFF;
  --text: #000000;

  --border-default-color: #E9E7DC;
  --border-default-width: 1px;
  --border-default-radius: 6px;

  --button: #000000;
  --button-rgb: 0, 0, 0;
  --button-text: #ffffff;
  --button-border-radius: 100px;
  --button-border-width: 1px;
  --button-border-color: ;

  --button-hover: #000000;
  --button-hover-text: #ffffff;

  --secondary-button: #FFFFFF;
  --secondary-button-text: #000000;
  --secondary-button-hover: #000000;
  --secondary-button-hover-text: #FFFFFF;

  --input: #E9E7DC;
  --input-bg: #ffffff;
  --input-text: #6b7280;
  --input-focus-bg: #ffffff;
  --input-border-radius: 8px;

  --neutral-50: #F3F3F3;
  --neutral-100: #EAEAEA;
  --neutral-200: #D4D4D4;
  --neutral-300: #B3B3B3;
  --neutral-400: #999999;
  --neutral-500: #808080;
  --neutral-600: #666666;
  --neutral-700: #4D4D4D;
  --neutral-800: #333333;
  --neutral-900: #1A1A1A;
  --accent-100: #FBFAF8;
}

They are defined in the app/views/themes/default/spree/shared/_css_variables.html.erb file which should be present in your theme.

Customizing with @theme

Tailwind 4 uses the @theme directive for customizations. You can extend or override the default theme:

css
@import "tailwindcss";

@theme {
  /* Add custom colors using Spree's CSS variables */
  --color-primary: var(--primary);
  --color-accent: var(--accent);
  --color-danger: var(--danger);
  --color-success: var(--success);

  /* Add custom fonts */
  --font-display: "Playfair Display", serif;

  /* Add custom spacing */
  --spacing-18: 4.5rem;

  /* Add custom border radius */
  --radius-button: var(--button-border-radius);
}

Then use them in your templates:

erb
<div class="bg-primary text-white font-display p-18 rounded-button">
  Custom styled content
</div>

Overriding Section Styles

Each section has CSS classes you can target to customize its appearance:

css
/* Section container classes follow the pattern: section-{section-type} */
.section-image-with-text {
  /* Custom styles for Image with Text section */
}

.section-featured-taxon {
  /* Custom styles for Featured Taxon section */
}

/* Block-specific styles within sections */
.image-with-text--heading {
  font-family: serif;
}

.rich-text--text {
  line-height: 1.8;
}

Using Tailwind Utility Classes

You can use Tailwind utility classes directly in your templates:

erb
<div class="flex items-center gap-4 p-6 bg-accent rounded-lg">
  <%= product.name %>
</div>

Arbitrary Values

Tailwind 4 supports arbitrary values for one-off customizations:

erb
<div class="p-[17px] bg-[#1a1a1a] text-[13px] grid-cols-[1fr_2fr]">
  Custom values
</div>

Variant Modifiers

Use variant modifiers for responsive and state-based styles:

erb
<div class="p-4 md:p-6 lg:p-8 hover:bg-accent active:scale-95">
  Responsive and interactive
</div>

Adding Custom Utilities

You can add custom utilities using standard CSS with the @utility directive:

css
@import "tailwindcss";

@utility content-auto {
  content-visibility: auto;
}

@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

Then use them like any other utility:

erb
<div class="content-auto scrollbar-hidden">
  <!-- Content -->
</div>

Adding Custom Variants

Create custom variants with the @variant directive:

css
@import "tailwindcss";

@variant pointer-coarse (@media (pointer: coarse));
@variant theme-dark (&:where([data-theme="dark"], [data-theme="dark"] *));

Use them in your templates:

erb
<button class="p-2 pointer-coarse:p-4 theme-dark:bg-gray-800">
  Touch-friendly button
</button>