Customizing Styles

In Sylius 2.x, customizing the visual appearance of the admin and shop interfaces is cleanly handled through CSS variables defined by the frontend frameworks used by each section:

• Admin Panel: Uses Tabler UI variables, exposing mostly by --tblr-*

• Shop Frontend: Uses Bootstrap variables, exposing mostly by --bs-*

This guide will walk you through how to locate, identify, and override these variables to implement custom themes or brand-aligned styles.

1. Identifying the Element to Customize

Before making any changes, you should identify the exact UI element you'd like to customize:

1. Open the relevant interface (Admin or Shop) in your browser.

2. Use Developer Tools (Right-click → Inspect)

3. In the Styles panel, look for applied custom properties (CSS variables), such as:

--tblr-primary: #206bc4;     /* Admin interface */
--bs-btn-bg: #0d6efd;        /* Shop interface */

These variables are usually defined globally via the :root, body, or * selectors. Once identified, you can override them in your own stylesheets to implement the desired look.

2. Overriding Admin Theme

To customize the admin layout theme (e.g., button colors, backgrounds, etc.).

Example 1: Change Primary Button Color in Admin

Let's inspect the Create button on the Taxon page. A few key facts:

• The button class is .btn-primary

• It relies on the variables --tblr-btn-bg and --tblr-btn-hover-bg

Create or edit a custom stylesheet:

/* assets/admin/styles/custom.scss */

.btn-primary {
    --tblr-btn-bg: #FF0000;
    --tblr-btn-hover-bg: #FF5531;
}

Then include it in your admin entrypoint:

// assets/admin/entrypoint.js

import './styles/custom.scss';

And build / rebuild your assets:

yarn build # or yarn watch

Result:

All the primary buttons are now red! 🎉

Example 2: Overriding the Base Primary Color in Admin

Inspect the button again:

• --tblr-btn-bg uses --tblr-primary

• --tblr-btn-hover-bg uses --tblr-primary-darken

Override these globally:

/* assets/admin/styles/custom.scss */

* {
    --tblr-primary: #FF0000;
    --tblr-primary-darken: #FF5531;
}

Rebuild assets:

yarn build # or yarn watch

Result:

All the base layout colors have been changed to red! 🎉

3. Overriding Shop Theme

The shop frontend uses Bootstrap, and its buttons rely on variables like --bs-btn-bg and --bs-btn-hover-bg.

Example 1: Change Primary Button Color in Shop

Inspect a primary button in the shop (e.g., "Add to cart") and note:

• Class: .btn-primary

• Variables: --bs-btn-bg, --bs-btn-hover-bg

Override them like this:

/* assets/shop/styles/custom.scss */

.btn-primary {
    --bs-btn-bg: #FF0000;
    --bs-btn-hover-bg: #FF5531;
}

Include this file in your shop entrypoint:

// assets/shop/entrypoint.js

import './styles/custom.scss';

Rebuild your assets:

yarn build # or yarn watch

Result:

All primary buttons in the shop are now red! 🎉

Example 2: Overriding the Base Primary Color in Shop

Sometimes it’s more effective to override the base variables used throughout Bootstrap, rather than styling individual components. However, the Shop theme is more granular than the Admin, so a few extra steps may be needed.

If you want to change the base primary color (e.g., from teal to red) across the entire shop, you’ll need to override several related variables. This includes buttons, links, and navigation elements—each of which may use distinct variables.

Here’s a comprehensive override example:

/* assets/shop/styles/custom.scss */

* {
  --bs-btn-bg: #FF0000 !important;              // All buttons
  --bs-btn-hover-bg: #FF5531 !important;        // Button hover state

  --bs-primary-rgb: 255, 0, 0;                   // RGB fallback
  --bs-primary: #FF0000;                         // Primary theme color

  --bs-link-color-rgb: 255, 0, 0;                // Link RGB
  --bs-link-color: #FF0000 !important;           // Link color (non-underlined)
  --bs-link-hover-color: #FF5531 !important;     // Link hover color
  --bs-link-hover-color-rgb: 255, 85, 49 !important;

  --bs-navbar-hover-color: #FF5531;              // Navbar hover links
  --bs-navbar-active-color: #FF5531;             // Navbar active link
}

If you don’t want to search for every individual variable—or if customizations don’t apply as expected—you can target element values directly. However, this is not the preferred approach:

/* assets/shop/styles/custom.scss */

a:hover {
    color: #FF5531 !important;
}

Rebuild assets:

yarn build # or yarn watch

Result:

The primary theme color across the shop is now red! 🎉

4. Scoping and Specificity

As you’ve seen throughout this guide, the key to customizing your frontend styles is identifying the correct variables through inspection and then overriding them in your own stylesheets.

If you want to customize the grid system, spacing, or any other part of Sylius, simply inspect the element and update the relevant CSS variables accordingly.

To limit changes to specific parts of your application, consider scoping your overrides more precisely—for example, by targeting only the components you want to customize.

php bin/console cache:clear