Create an Admin theme

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

Prerequisites

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

Overview

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

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):

<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>
Copied to your clipboard
<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:

<?php
/**
 * Copyright [first year code created] Adobe
 * All rights reserved.
 */
use \Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(ComponentRegistrar::THEME, 'adminhtml/%vendor_dir/your_theme_dir%', __DIR__); // Example: 'adminhtml/Magento/backend'
Copied to your clipboard
<?php
/**
 * Copyright [first year code created] Adobe
 * All rights reserved.
 */
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)

Admin theme logo (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:

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

Add the following sample code to the new file.

<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>
Copied to your clipboard
<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>

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.