Skip to content

[FEAT] Add theme changes for PS 9.1 #2088

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kpodemski merged 3 commits into from
Jan 15, 2026
Merged

[FEAT] Add theme changes for PS 9.1 #2088

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a228980
feat: add theme changes for PS 9.1
ga-devfront Jan 12, 2026
3876ca5
feat: refacto
ga-devfront Jan 12, 2026
e69e5cf
Eliminate redundancy in compatibility breaks section
kpodemski Jan 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
299 changes: 253 additions & 46 deletions modules/core-updates/9.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,67 +13,79 @@ menuTitle: Changes in 9.1.x

# Notable changes in PrestaShop 9.1.x

{{% notice warning %}}
**Draft documentation** - PrestaShop 9.1 is currently in beta. This documentation is subject to change as the release progresses.
{{% /notice %}}

This section provides a list of the most significant changes in PrestaShop 9.1.x for module and theme developers. If you notice any missing or incorrect information, please help us improve by creating an issue on our [GitHub repository](https://github.com/PrestaShop/docs/issues/new).

{{% notice info %}}
As a minor version, PrestaShop 9.1 strives to maintain backward compatibility with 9.0.x. Breaking changes are only introduced when absolutely necessary. For more details, see our [Backward Compatibility Promise](https://github.com/PrestaShop/ADR/blob/master/0017-backward-compatibility-promise.md).
{{% notice warning %}} **Draft documentation** - PrestaShop 9.1 is currently in
beta. This documentation is subject to change as the release progresses. {{%
/notice %}}

This section provides a list of the most significant changes in PrestaShop 9.1.x
for module and theme developers. If you notice any missing or incorrect
information, please help us improve by creating an issue on our
[GitHub repository](https://github.com/PrestaShop/docs/issues/new).

{{% notice info %}} As a minor version, PrestaShop 9.1 strives to maintain
backward compatibility with 9.0.x. Breaking changes are only introduced when
absolutely necessary. For more details, see our
[Backward Compatibility Promise](https://github.com/PrestaShop/ADR/blob/master/0017-backward-compatibility-promise.md).
{{% /notice %}}

## Breaking Changes

### Theme::getDefaultTheme() method

The `Theme::getDefaultTheme()` method no longer returns a hardcoded "classic" value. It now returns the actual default theme from configuration.
The `Theme::getDefaultTheme()` method no longer returns a hardcoded "classic"
value. It now returns the actual default theme from configuration.

Related pull request: [Introduce Theme::getDefaultTheme method to replace classic hard-coded value](https://github.com/PrestaShop/PrestaShop/pull/40295)
Related pull request:
[Introduce Theme::getDefaultTheme method to replace classic hard-coded value](https://github.com/PrestaShop/PrestaShop/pull/40295)

**Before (9.0.x):**

```php
// Always returned "classic"
$defaultTheme = Theme::getDefaultTheme();
```

**After (9.1.x):**

```php
// Returns the configured default theme (e.g., "hummingbird")
$defaultTheme = Theme::getDefaultTheme();
```

If your code assumes the default theme is "classic", update it to handle any theme name or use `Theme::getDefaultTheme()` dynamically.
If your code assumes the default theme is "classic", update it to handle any
theme name or use `Theme::getDefaultTheme()` dynamically.

### D3 and NVD3 Libraries Updated

The D3 and NVD3 charting libraries have been updated to newer versions.

Related pull request: [Update d3 and nvd3 libs](https://github.com/PrestaShop/PrestaShop/pull/39629)

If your module creates custom dashboard widgets or charts using these libraries, test for compatibility.
Related pull request:
[Update d3 and nvd3 libs](https://github.com/PrestaShop/PrestaShop/pull/39629)

If your module creates custom dashboard widgets or charts using these libraries,
test for compatibility.

## New Hooks

### Module Lifecycle Hooks

New hooks allow you to react to module enable, disable, and upgrade events:

| Hook | Description |
|------|-------------|
| [`actionModuleEnable`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/actionModuleEnable" >}}) | Triggered after a module is enabled |
| [`actionModuleDisable`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/actionModuleDisable" >}}) | Triggered after a module is disabled |
| Hook | Description |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| [`actionModuleEnable`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/actionModuleEnable" >}}) | Triggered after a module is enabled |
| [`actionModuleDisable`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/actionModuleDisable" >}}) | Triggered after a module is disabled |
| [`actionModuleUpgradeAfter`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/actionModuleUpgradeAfter" >}}) | Triggered after a module is upgraded |

Related pull request: [Add hooks on Module enable/disable/upgrade](https://github.com/PrestaShop/PrestaShop/pull/38839)
Related pull request:
[Add hooks on Module enable/disable/upgrade](https://github.com/PrestaShop/PrestaShop/pull/38839)

### Configuration Hook

A new hook is triggered when configuration values are updated:

| Hook | Description |
|------|-------------|
| Hook | Description |
| --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [`actionConfigurationUpdateValueBefore`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/actionConfigurationUpdateValueBefore" >}}) | Triggered before `Configuration::updateValue()` is called |

- [Add hook on Configuration updateValue](https://github.com/PrestaShop/PrestaShop/pull/38956)
Expand All @@ -82,7 +94,8 @@ A new hook is triggered when configuration values are updated:

### [prestashop:thumbnails:regenerate]({{< relref "/9/development/components/console/prestashop-thumbnails-regenerate" >}})

Regenerate product image thumbnails from the command line. Useful for batch processing after image type changes.
Regenerate product image thumbnails from the command line. Useful for batch
processing after image type changes.

- [Add console command "prestashop:thumbnails:regenerate"](https://github.com/PrestaShop/PrestaShop/pull/39478)

Expand All @@ -92,7 +105,8 @@ php bin/console prestashop:thumbnails:regenerate

### [prestashop:search:index]({{< relref "/9/development/components/console/prestashop-search-index" >}})

Rebuild the search index from the command line. Useful for cron jobs or after bulk product imports.
Rebuild the search index from the command line. Useful for cron jobs or after
bulk product imports.

- [Add SearchIndexationCommand to handle CLI search indexation](https://github.com/PrestaShop/PrestaShop/pull/39403)

Expand All @@ -112,49 +126,242 @@ php bin/console prestashop:module:export-translations <module_name>

## Multi-Shipment System

{{% notice note %}}
The multi-shipment feature is behind a feature flag and is disabled by default.
{{% /notice %}}
{{% notice note %}} The multi-shipment feature is behind a feature flag and is
disabled by default. {{% /notice %}}

{{% notice warning %}}
**Work in Progress** - The multi-shipment system is still under active development. While we encourage module developers to explore the new features and ensure compatibility, please note that changes may be introduced in future releases. Any significant updates will be documented accordingly.
{{% /notice %}}
{{% notice warning %}} **Work in Progress** - The multi-shipment system is still
under active development. While we encourage module developers to explore the
new features and ensure compatibility, please note that changes may be
introduced in future releases. Any significant updates will be documented
accordingly. {{% /notice %}}

PrestaShop 9.1 introduces a multi-shipment system allowing orders to be split across multiple carriers. This is a major architectural change that will affect modules interacting with order shipments and carriers.
PrestaShop 9.1 introduces a multi-shipment system allowing orders to be split
across multiple carriers. This is a major architectural change that will affect
modules interacting with order shipments and carriers.

For an overview of this feature and its capabilities, read the announcement: [Introducing Shipments in PrestaShop 9.1](https://build.prestashop-project.org/news/2026/introducing-shipments/)
For an overview of this feature and its capabilities, read the announcement:
[Introducing Shipments in PrestaShop 9.1](https://build.prestashop-project.org/news/2026/introducing-shipments/)

Detailed developer documentation for this feature will be added once the implementation is finalized.
Detailed developer documentation for this feature will be added once the
implementation is finalized.

## New Discount System

{{% notice note %}}
The new discount system is behind a feature flag and is disabled by default.
{{% /notice %}}
{{% notice note %}} The new discount system is behind a feature flag and is
disabled by default. {{% /notice %}}

{{% notice warning %}}
**Work in Progress** - The discount system is still under active development. While we encourage module developers to explore the new features and ensure compatibility, please note that changes may be introduced in future releases. Any significant updates will be documented accordingly.
{{% /notice %}}
{{% notice warning %}} **Work in Progress** - The discount system is still under
active development. While we encourage module developers to explore the new
features and ensure compatibility, please note that changes may be introduced in
future releases. Any significant updates will be documented accordingly. {{%
/notice %}}

PrestaShop 9.1 introduces a completely redesigned discount management interface and architecture. While it uses the existing cart rules system under the hood, it features an improved implementation with a completely revamped design and new approaches to managing and combining discounts. This is a major change that will affect modules interacting with discounts and promotions.
PrestaShop 9.1 introduces a completely redesigned discount management interface
and architecture. While it uses the existing cart rules system under the hood,
it features an improved implementation with a completely revamped design and new
approaches to managing and combining discounts. This is a major change that will
affect modules interacting with discounts and promotions.

For an overview of this feature and its capabilities, read the announcement: [Improved Discounts System in PrestaShop 9.1](https://build.prestashop-project.org/news/2026/improved-discounts-system/)
For an overview of this feature and its capabilities, read the announcement:
[Improved Discounts System in PrestaShop 9.1](https://build.prestashop-project.org/news/2026/improved-discounts-system/)

Detailed developer documentation for this feature will be added once the implementation is finalized.
Detailed developer documentation for this feature will be added once the
implementation is finalized.

## Hummingbird Theme

Hummingbird is now the default theme for new PrestaShop 9.1 installations.

{{% notice info %}}
Existing installations upgrading from 9.0.x keep their current theme. Hummingbird is only set as default for fresh installations.
{{% /notice %}}
{{% notice info %}} Existing installations upgrading from 9.0.x keep their
current theme. Hummingbird is only set as default for fresh installations. {{%
/notice %}}

Hummingbird introduces compatibility breaks compared to the Classic theme. If
module developers wish to ensure their modules remain compatible, we invite them
to review the changes listed below.

### Hooks

Some hooks have been removed or replaced in Hummingbird. Below is a list of key
changes to be aware of:

- **`displaySearch`**: This hook was previously used to inject an instance of
the `ps_searchbar` module into the 404 page. It caused conflict issues
(duplicate display), which is why it has been removed in Hummingbird.
- **`displayOrderDetail`**: Replaces the variable hook
`$HOOK_DISPLAYORDERDETAIL`. It functions in the same way but follows the
standard hook naming convention.
- **`displayModalContent`**: A new hook that allows module developers to inject
content into the modal container.

### Bootstrap

{{% notice note %}} Bootstrap has been updated from **4.0.0-alpha.5** →
**5.3.3** {{% /notice %}}

For a complete guide on migrating from v4 to v5, please refer to the
[official Bootstrap migration documentation](https://getbootstrap.com/docs/5.3/migration/).

#### Breaking changes that can impact module developers:

{{% notice warning %}} The following changes in Bootstrap 5 may impact the
display and functionality of your modules. We strongly recommend reviewing these
items and updating your tpl/css/js files to ensure full compatibility with the
new theme. {{% /notice %}}

##### Grid & Layout system

- **Breakpoints**:

| Breakpoint | Class infix | Dimensions |
| ----------------- | ----------- | ------------ |
| Extra Extra Small | None | **< 360px** |
| Extra Small | `xs` | **≥ 360px** |
| Small | `sm` | **≥ 576px** |
| Medium | `md` | **≥ 768px** |
| Large | `lg` | **≥ 992px** |
| Extra Large | `xl` | **≥ 1200px** |
| Extra Extra Large | `xxl` | **≥ 1400px** |

- **Gutters**: Renamed `.no-gutters` to `.g-0` to match new gutter utilities.
- **Columns**: Columns no longer have `position: relative` applied. You may have
to add `.position-relative` to some elements to restore that behavior.
- **Order classes**: Dropped several `.order-*` classes. Only `.order-0` to
`.order-5` are provided out of the box.
- **Media Object**: Dropped the `.media` component in favor of flex utilities.
[See example](https://getbootstrap.com/docs/5.3/utilities/flex#media-object).

##### Forms

- **Consolidated native and custom form elements**: Checkboxes, radios, selects,
and other inputs now use unified classes:
- `.custom-control.custom-checkbox` → `.form-check`.
- `.custom-control.custom-radio` → `.form-check`.
- `.custom-control.custom-switch` → `.form-check.form-switch`.
- `.custom-select` → `.form-select`.
- `.custom-file` and `.form-control-file` → replaced by custom styles on
`.form-control`.
- `.custom-range` → `.form-range`.
- **Input Groups**: Dropped `.input-group-append` and `.input-group-prepend`.
Add buttons and `.input-group-text` as direct children of input groups.
- **Layout**: Dropped specific layout classes (`.form-group`, `.form-row`,
`.form-inline`) in favor of grid and utilities.
- **Labels**: Form labels now require `.form-label`.
- **Form Text**: `.form-text` no longer sets `display`.
- **Toggle Buttons**: Checkboxes/radios with toggle buttons no longer require a
wrapping element. Add `.btn-check` to the `<input>` and pair with `.btn`
classes on the `<label>`.

##### Components

- **Buttons**:
- Dropped `.btn-block` in favor of `.d-grid` and `.gap-*` utilities.
[See examples](https://getbootstrap.com/docs/5.3/components/buttons#block-buttons).
- `.close` renamed to `.btn-close`.
- **Cards**:
- Dropped `.card-deck` in favor of grid (`.row-cols-*`).
- Dropped `.card-columns` in favor of Masonry.
- Replaced `.card` based accordion with the new
[Accordion component](https://getbootstrap.com/docs/5.3/components/accordion).
- **Badges**:
- Dropped all `.badge-*` color classes (use background utilities like
`.bg-primary`).
- Dropped `.badge-pill` (use `.rounded-pill`).
- **Jumbotron**: Dropped, use utilities instead.
- **Navbars**: Now require a container within.
- **Navs**: `.active` class must be applied to `.nav-link`s, not `.nav-item`s.
- **Popovers/Tooltips**: Renamed `.arrow` to `.popover-arrow` /
`.tooltip-arrow`.

##### Utilities & Helpers

- **RTL Support (Renaming)**: Several utilities renamed for logical properties:
- `.float-left`/`.right` → `.float-start`/`.end`.
- `.border-left`/`.right` → `.border-start`/`.end`.
- `.rounded-left`/`.right` → `.rounded-start`/`.end`.
- `.ml-*` / `.mr-*` → `.ms-*` / `.me-*`.
- `.pl-*` / `.pr-*` → `.ps-*` / `.pe-*`.
- `.text-*-left` / `.right` → `.text-*-start` / `.end`.
- **Backgrounds**: Use `.bg-gradient` combined with `.bg-{color}` instead of
`.bg-gradient-{color}` classes.
- **Text**:
- Removed `.text-hide`.
- `.text-*` utilities no longer add hover/focus states to links. Use `.link-*`
helpers.
- Dropped `.text-justify`.
- `.text-monospace` -> `.font-monospace`.
- **Spacing**: Disabled negative margins by default.
- **Fonts**:
- `.font-weight-*` → `.fw-*`.
- `.font-italic` → `.fst-italic`.
- **Borders**: Removed `.rounded-sm`/`.lg`. Introduced `.rounded-0` to
`.rounded-3`.
- **Ratio**: `.embed-responsive` helpers renamed to `.ratio` helpers (e.g.
`.ratio-16x9`).
- **Visually Hidden**: `.sr-only` replaced by `.visually-hidden`.

##### Javascript & Data Attributes

- **Data Attributes**: All JavaScript plugins are now namespaced (e.g.,
`data-bs-toggle` instead of `data-toggle`).
- **Dropdowns**:
- Events triggered on toggle button and bubble up.
- Dropped `flip` option for `fallbackPlacements`.
- **PopperConfig**: Default `fallbackPlacements` changed to
`['top', 'right', 'bottom', 'left']`.

##### Tables

- **Nested tables**: Do not inherit styles anymore.
- **Headings**: `.thead-light` and `.thead-dark` dropped in favor of `.table-*`
variant classes.

### Javascript

#### JQuery

JQuery is now deprecated and will be removed in the next major Hummingbird
version planned to be released with PrestaShop 10. This change aligns with the
Bootstrap 5 update, which dropped jQuery dependency. **Developers are encouraged
to use Vanilla JS, utilizing PrestaShop helper functions and
[native Bootstrap 5 features](https://getbootstrap.com/docs/5.3/getting-started/javascript/)
where possible.**

#### JS Selectors

Non-standard selectors that are not part of Bootstrap or our core CSS (e.g.,
`js-top-menu mobile`) have been removed (from JS, they are still available in
templates) in favor of **data attributes**. To maintain a clean separation of
concerns, we now use CSS classes exclusively for styling and data attributes for
programmatic logic.

{{% notice note %}} This migration is **progressive**. Not all selectors have
been updated yet due to Core limitations, but the long-term goal is to migrate
all of them to this new standard. We encourage you to use new data attributes
instead of old CSS classes.{{% /notice %}}

**Example Change:**

- **Before:** `#password-feedback` (ID selector)
- **After:** `[data-ps-ref="password-feedback-template"]` (Data attribute)

**Naming Convention:** All new or updated selectors now start with `data-ps`
followed by a specific indicator:

- `ref`: For referencing an element (e.g., `data-ps-ref`)
- `action`: For defining an action (e.g., `data-ps-action`)
- `target`: For the target of an action (e.g., `data-ps-target`)

_This convention will be further documented in the Theme Development
documentation._

## Database Changes

PrestaShop 9.1 includes database schema changes to support new features like multi-shipment and the improved discount system.
PrestaShop 9.1 includes database schema changes to support new features like
multi-shipment and the improved discount system.

You can review all database changes in the upgrade SQL file: [9.1.0.sql](https://github.com/PrestaShop/autoupgrade/blob/dev/upgrade/sql/9.1.0.sql)
You can review all database changes in the upgrade SQL file:
[9.1.0.sql](https://github.com/PrestaShop/autoupgrade/blob/dev/upgrade/sql/9.1.0.sql)

## Infrastructure Changes

Expand Down