Create an Admin theme

What’s in this topic

This topic describes how to create your custom theme for Magento 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:

Create a theme directory.
Add a declaration theme.xml.
Add registration.php.
Optionally add composer.json.
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 Magento 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>

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 Magento 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 © 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)

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>
            </arguments>
        </referenceBlock>
    </body>
 </page>

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

Theme registration

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