Skip to main content

How to style error pages in Sylius

· 2 min read
Stephan Hochdörfer
Stephan Hochdörfer
Head of IT Business Operations

A recent question in the Sylius Slack community asked how to customize error pages in Sylius 2.x. Having just tackled this challenge in one of our own merchant projects, I was able to provide some valuable guidance and insights.

Basically, you have two options when you want to style (or customize) the existing error pages in Sylius.

1. Overwrite the templates provided by Sylius​

The error pages for Sylius Admin are located in vendor/sylius/sylius/src/Sylius/Bundle/AdminBundle/templates/errors while the error pages for Sylius Shop are located in vendor/sylius/sylius/src/Sylius/Bundle/ShopBundle/templates/errors.

You can overwrite the templates by copying them to your project and then adjusting them. The Admin templates need to be copied to templates/bundles/SyliusAdminBundle/errors and the Shop templates need to be copied to templates/bundles/SyliusShopBundle/errors.

This is the "Symfony way" of overwriting templates in your own project. Use this way if you need full control over the error pages, e.g., you want to change the layout or the structure of the error pages.

2. Use Sylius Twig Hooks to overwrite or add additional content to the existing templates​

This is the method I would prefer and call it the "Sylius way". Use the existing Twig hooks to use a different template or to add additional content to the existing template.

Sylius defines these Twig hooks for the respective 403, 404, and 500 error pages:

  • sylius_admin.errors.404
  • sylius_shop.error403.error.layout
  • sylius_shop.error404.error.layout
  • sylius_shop.error500.error.layout

For example, you can overwrite the existing message hookable by redefining it in your config/packages/sylius_twig_hooks.yaml file:

sylius_twig_hooks:
    hooks:
        'sylius_shop.error404.error.layout':
            message:
                template: 'templates/errors/error404/layout/message.html.twig'
                priority: 0

Or, you could add additional content, adding a new hookable footer in your config/packages/sylius_twig_hooks.yaml file:

sylius_twig_hooks:
    hooks:
        'sylius_shop.error404.error.layout':
            footer:
                template: 'templates/errors/error404/layout/footer.html.twig'
                priority: 0

If you want to know more about how to work with Twig hooks, have a look at the Twig Hooks documentation.