Adobe Commerce 2.3 reached end of support in September 2022.

Create an Admin theme

What’s in this topic

This topic describes how to create your custom theme for Admin, referencing the similar flow for creating a custom storefront theme.

Prerequisites

Set your Magento application to the developer mode. The application mode influences the way static files are cached by Magento.

Overview

To create a custom Admin theme, take the following steps:

  1. Create a theme directory.
  2. Add a declaration theme.xml.
  3. Add registration.php.
  4. Optionally add composer.json.
  5. Optionally change theme logo.

Each step is described further.

Create a theme directory

In the app/design/adminhtml directory create a new <Vendor>/<admin_theme> directory.

Add a declaration theme.xml

In the theme directory, add theme.xml containing at least the theme name and the parent theme name (if the theme inherits from one). We recommend you to inherit from the default Admin theme: Magento/backend.

Add or copy from an existing theme.xml to your theme directory app/design/adminhtml/<Vendor>/<admin_theme>.

Configure it using the following example (replace placeholders with your theme information):

1
2
3
4

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
     <title>%Theme title%</title> <!-- your theme's name -->
     <parent>%vendor_dir%/%parent_theme_dir%</parent> <!-- the parent theme. Example: Magento/backend -->
</theme>

If you change the theme title or parent theme information in theme.xml after a theme was already registered, you need to open or reload any Admin page for your changes to be saved in the database.

Add registration.php

In your theme directory, create a registration.php file. In this file, add the following code, having replaced placeholders with your theme information:

1
2
3
4
5
6
7

<?php
/**
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
 */
use \Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(ComponentRegistrar::THEME, 'adminhtml/%vendor_dir/your_theme_dir%', __DIR__); // Example: 'adminhtml/Magento/backend'

Optionally add composer.json

See the Make your theme a Composer package (optional)

In the default Magento/backend theme lib/web/images/magento-logo.svg is used as theme logo. To override it, in your theme directory, create a web/images sub-directory, and add your custom file named magento-logo.svg. If you want to use the file with other name and/or format, you need to additionally declare it as described in Declaring theme logo.

To customize the Admin theme logo:

  1. Create a new XML file in the theme named app/design/adminhtml/<Vendor>/<theme>/Magento_Backend/layout/admin_login.xml.

  2. Add the following sample code to the new file.

    1
2
3
4
5
6
7
8
9
10
11

    <page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="admin-login" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="logo">
            <arguments>
                <argument name="logo_image_src" xsi:type="string">images/custom-logo.svg</argument>
                <argument name="logo_width" xsi:type="number">150</argument> <!-- Add custom logo width -->
                <argument name="logo_height" xsi:type="number">80</argument> <!-- Add custom logo height -->
            </arguments>
        </referenceBlock>
    </body>
 </page>

  3. Add your custom logo to the app/design/adminhtml/<Vendor>/<theme>/web/images/ directory.

Theme registration

Once you open the Admin (or reload any Admin page) having added the theme files to the files system, your theme gets registered and added to the database.

Apply the Admin theme

See the Apply a custom Admin theme topic.

© 2023 Adobe. All rights reserved.