Guidelines for Back Office Modules Theming

Introduction

To ensure a good user experience we recommend designing your module to adapt its style to the BO version. For example, on PrestaShop 9, use a black-and-white style; otherwise, match the BO theme.

We recommend supporting PrestaShop versions from 1.7.3.0 to 1.7.8.0 and 9.0.0 onward, as these versions introduce significant BO themes updates.

Resources and Tools

  • Dev Docs PrestaShop UI Kit → Discover most of the Bootstrap components included in the new-theme of the PrestaShop 9 Back Office, used on Symfony pages.
  • PrestaShop BO Rebrand → Learn how to preview most of the Bootstrap components included in the default theme of the PrestaShop 9 Back Office, used on Legacy pages
  • PrestaShop BO Themes Package → This is an experimental repository that provides access to the compiled styles of Back Office themes. It includes both the default and new-theme back office styles for versions v1.7.3.0, v1.7.8.0, and v9.0.0, showcasing relevant changes across Back Office theme styles.
  • Variables mapping between BO versions

Steps to Handle BO Module Theming

  1. Prepare your module for compatibility with BO version styling
    • Design your module to fit inside a div with a class that identifies the BO versions. By doing this, you will be able to adapt its style based on the BO theme.
  2. For legacy templates
  3. For Symfony templates
  4. Base your custom templating on PrestaShop 9
    • Build your template using v9 as the base version and define default CSS variables specific to this version.
  5. Adjust CSS variables for compatibility with older versions
    • Based on the class used to identify the theme versions, redefine necessary CSS variables (e.g., colors, background colors, radius variables) to match the corresponding BO theme.

1. Prepare your module for compatibility with BO version styling

By wrapping your module inside a div with a class that identifies the range of BO (Back Office) versions, you can assign custom styles specific to that version. This approach allows your module’s interface to adapt to different PrestaShop versions.

For example, if the detected PrestaShop version is 1.7.3.0, you can create a class named → v1-7-3-0 and include it in your template to wrap your entire module.

Retrieve the PrestaShop version class to be able to expose it in the template:

private function getPsVersionClass(): string
{
  $psVersion = _PS_VERSION_;
  $psClass = '';

  if (version_compare($psVersion, '1.7.8.0', '<')) {
    $psClass = 'v1-7-3-0';
  } elseif (version_compare($psVersion, '9.0.0', '<')) {
    $psClass = 'v1-7-8-0';
  }

  // You can add more versions here if needed...

  return $psClass;
}

Expose the PrestaShop version class through the template:

Smarty version :

// Get the PrestaShop version class
$psVersionClass = $this->getPsVersionClass();

// Assign to Smarty template
$this->context->smarty->assign('psVersionClass', $psVersionClass);

Twig version :

// Get the PrestaShop version class
$psVersionClass = $this->getPsVersionClass();

// Assign to Twig template
$this->getTwig()->render('path/to/template.html.twig', [
  'psVersionClass' => $psVersionClass,
]);

Template render example:

<!-- Twig -->
<div class="{{ psVersionClass }}" id="my_module"></div>

<!-- Smarty -->
<div class="{ $psVersionClass }" id="my_module"></div>

<!-- HTML Result -->
<div class="v1-7-3-0" id="my_module">
  <!-- All the module template goes here -->
</div>
Doing this ensures that your module styling remains adaptable across different PrestaShop versions.

2. For legacy templates

If your module uses a legacy template, it is recommended to use Bootstrap components provided within the PrestaShop default theme. These components ensure consistent design and functionality across the Back Office, aligning your module with PrestaShop’s styling standards.

PrestaShop’s default theme includes a variety of pre-styled Bootstrap elements, such as buttons, forms elements and alerts… that you can incorporate into your module templates. These components has been totally rebranded in PrestaShop 9, providing a polished and unified look.

How to see default theme components.

3. For Symfony templates

If your module uses a Symfony template, it is recommended to use Bootstrap components provided within the PrestaShop UI Kit. These components ensure consistent design and functionality across the Back Office, aligning your module with PrestaShop’s styling standards.

PrestaShop’s new-theme theme includes a variety of pre-styled Bootstrap elements, such as buttons, forms elements and alerts… that you can incorporate into your module templates. These components has been totally rebranded in PrestaShop 9, providing a polished and unified look.

See PrestaShop UI Kit components.

4. Base your custom templating on PrestaShop 9

If your module is designed to be installed on PrestaShop 9 or earlier versions, base your templating on the PrestaShop 9 version. We strongly recommend using CSS variables for your custom styling, with their definitions set at the :root level.

These variables should reference those available through the Back Office in v9, especially for color-related variables. For variables defined in :root, include fallback values in their declarations to ensure compatibility with all BO versions, including those that do not expose CSS variables (versions below 9.0.0).

New variables exposed on PrestaShop 9 Back Office can be found on PrestaShop UI Kit variables reference.

This approach ensures your variables remain aligned with PrestaShop’s new brand identity.

Lastly, we recommend using a unique prefix when defining your variables to avoid conflicts with other variables in the BO.

Variables setting examples:

$id: "#my_module";
$module-prefix: "m-";
$cdk-prefix: "cdk-";

/* CSS variables */
/* 9.0.0 */
:root {
  /* Primitive */
  --#{$module-prefix}primary-800: var(--#{$cdk-prefix}primary-800, #1d1d1b);
  --#{$module-prefix}primary-700: var(--#{$cdk-prefix}primary-700, #3f3f3d);
  --#{$module-prefix}primary-600: var(--#{$cdk-prefix}primary-600, #5e5e5e);
  --#{$module-prefix}primary-500: var(--#{$cdk-prefix}primary-500, #bbbbbb);
  --#{$module-prefix}primary-400: var(--#{$cdk-prefix}primary-400, #dddddd);
  --#{$module-prefix}primary-200: var(--#{$cdk-prefix}primary-200, #f7f7f7);
  // ...

  /* Global */
  --#{$module-prefix}base-text-color: var(--#{$module-prefix}primary-800);
  --#{$module-prefix}base-text-color-hover: var(--#{$module-prefix}primary-700);
  --#{$module-prefix}primary: var(--#{$module-prefix}primary-800);
  --#{$module-prefix}primary-hover: var(--#{$module-prefix}primary-700);
}

5. Adjust CSS variables for compatibility with older versions

Once you have styled your module and custom components using a set of CSS variables for visual properties in the v9 version, you can adapt this styling for previous versions of the Back Office by reassigning specific values based on the PrestaShop BO version.

Variables reassign examples:

:root {
  --#{$module-prefix}base-text-color: var(--#{$module-prefix}primary-800);
  --#{$module-prefix}primary: var(--#{$module-prefix}primary-800);
  --#{$module-prefix}primary-hover: var(--#{$module-prefix}primary-700);
}

/* 1.7.8.0 */
.v1-7-8-0 {
  --#{$module-prefix}base-text-color: #555555;
  --#{$module-prefix}primary: #25b9d7;
  --#{$module-prefix}primary-hover: #1a8196;
}

/* 1.7.3.0 */
.v1-7-3-0 {
  --#{$module-prefix}base-text-color: #555555;
  --#{$module-prefix}primary: #00aff0;
  --#{$module-prefix}primary-hover: #008abd;
}

Usage example inside a custom component:

/* Custom example */
$e: ".custom-btn";

#{$id} {
  #{$e} {
    --#{$module-prefix}btn-color: var(--#{$module-prefix}base-text-color);
    --#{$module-prefix}btn-bg-color: var(--#{$module-prefix}primary);
    --#{$module-prefix}btn-bg-color-hover: var(--#{$module-prefix}primary);

    color: var(--#{$module-prefix}btn-color);
    background-color: var(--#{$module-prefix}btn-bg-color);
    //...

    &:hover {
      background-color: var(--#{$module-prefix}btn-bg-color-hover);
    }
  }
}

Variables Mapping

Here is a table that maps the CSS variables used in the PrestaShop 9 Back Office to their corresponding variables in previous versions.

This table is designed to assist you in mapping new variables to older values, making it easier to style your custom components effectively.

Use Case Up to 9.0.0 1.7.8.0 to 8.x.x 1.7.3.0 to 1.7.7.8
Primary
#fafafa
100
#f7f7f7
200
#eeeeee
300
#dddddd
400
#bbbbbb
500
#5e5e5e
600
#3f3f3d
700
#1d1d1b
800
#101010
900
#25b9d7
N/A
#00aff0
N/A
Primary states
#1d1d1b
normal
#373734
hover
#25b9d7
normal
#1e94ab
hover
#00aff0
normal
#008abd
hover
Base text color
#1d1d1b
N/A
#555555
N/A
#555555
N/A
Green
#eaf8ef
50
#bde9c9
100
#59af70
300
#207f4b
500
#cbf2d4
50
...
N/A
...
N/A
#53d572
500
#ddf0de
50
...
N/A
...
N/A
#72C279
500
Yellow
#fff5e5
50
#ffeccc
100
#ffd999
300
#ffa000
500
#fffbd3
50
...
N/A
...
N/A
#fab000
500
#fff3d7
50
...
N/A
...
N/A
#fcc94f
500
Red
#ffe4e6
50
#fdbfbf
100
#d63f3c
300
#ba151a
500
#a41913
700
#fbc6c3
50
...
N/A
...
N/A
#f44336
500
...
N/A
#ffe2e4
50
...
N/A
...
N/A
#eab3b7
500
...
N/A
Blue
#e8edfd
50
#d1dcfc
100
#a2b8f9
300
#174eef
500
#2942cc
700
#beeaf3
50
...
N/A
...
N/A
#25b9d7
500
...
N/A
#dcf4f9
50
...
N/A
...
N/A
#4ac7e0
500
...
N/A
Border
#dddddd
#dddddd
#dddddd
Radius
0
0.5rem
0.3125rem