Customizing admin templates¶
In your projects with Wagtail, you may wish to replace elements such as the Wagtail logo within the admin interface with your own branding. This can be done through Django’s template inheritance mechanism.
You need to create a templates/wagtailadmin/
folder within one of your apps - this may be an existing one or a new one created for this purpose, for example, dashboard
. This app must be registered in INSTALLED_APPS
before wagtail.admin
:
INSTALLED_APPS = (
# ...
'dashboard',
'wagtail',
'wagtail.admin',
# ...
)
Custom branding¶
The template blocks that are available to customize the branding in the admin interface are as follows:
branding_logo
¶
To replace the default logo, create a template file dashboard/templates/wagtailadmin/base.html
that overrides the block branding_logo
:
{% extends "wagtailadmin/base.html" %}
{% load static %}
{% block branding_logo %}
<img src="{% static 'images/custom-logo.svg' %}" alt="Custom Project" width="80" />
{% endblock %}
The logo also appears on the following pages and can be replaced with its template file:
login page - create a template file
dashboard/templates/wagtailadmin/login.html
that overwrites thebranding_logo
block.404 error page - create a template file
dashboard/templates/wagtailadmin/404.html
that overrides thebranding_logo
block.wagtail userbar - create a template file
dashboard/templates/wagtailadmin/userbar/base.html
that overwrites thebranding_logo
block.
branding_favicon
¶
To replace the favicon displayed when viewing admin pages, create a template file dashboard/templates/wagtailadmin/admin_base.html
that overrides the block branding_favicon
:
{% extends "wagtailadmin/admin_base.html" %}
{% load static %}
{% block branding_favicon %}
<link rel="shortcut icon" href="{% static 'images/favicon.ico' %}" />
{% endblock %}
branding_title
¶
To replace the title prefix (which is ‘Wagtail’ by default), create a template file dashboard/templates/wagtailadmin/admin_base.html
that overrides the block branding_title
:
{% extends "wagtailadmin/admin_base.html" %}
{% block branding_title %}Frank's CMS{% endblock %}
branding_login
¶
To replace the login message, create a template file dashboard/templates/wagtailadmin/login.html
that overrides the block branding_login
:
{% extends "wagtailadmin/login.html" %}
{% block branding_login %}Sign in to Frank's Site{% endblock %}
branding_welcome
¶
To replace the welcome message on the dashboard, create a template file dashboard/templates/wagtailadmin/home.html
that overrides the block branding_welcome
:
{% extends "wagtailadmin/home.html" %}
{% block branding_welcome %}Welcome to Frank's Site{% endblock %}
Custom user interface fonts¶
To customize the font families used in the admin user interface, inject a CSS file using the hook insert_global_admin_css and override the variables within the :root
selector:
:root {
--w-font-sans: Papyrus;
--w-font-mono: Courier;
}
Custom user interface colors¶
Warning
The default Wagtail colors conform to the WCAG2.1 AA level color contrast requirements. When customizing the admin colors you should test the contrast using tools like Axe.
To customize the colors used in the admin user interface, inject a CSS file using the hook insert_global_admin_css and set the desired variables within the :root
selector. Color variables are reused across both the light and dark themes of the admin interface. To change the colors of a specific theme, use:
:root, .w-theme-light
for the light theme..w-theme-dark
for the dark theme.@media (prefers-color-scheme: light) { .w-theme-system { […] }}
for the light theme via system settings.@media (prefers-color-scheme: dark) { .w-theme-system { […] }}
for the dark theme via system settings.
There are two ways to customize Wagtail’s color scheme:
Set static color variables, which are then reused in both light and dark themes across a wide number of UI components.
Set semantic colors, which are more numerous but allow customizing specific UI components.
For static colors, either set each color separately (for example --w-color-primary: #2E1F5E;
); or separately set HSL (--w-color-primary-hue
, --w-color-primary-saturation
, --w-color-primary-lightness
) variables so all shades are customized at once. For example, setting --w-color-secondary-hue: 180;
will customize all of the secondary shades at once.
Make sure to test any customisations against our Contrast Grid. Try out your own customisations with this interactive style editor:
Static colours
Variable | Usage | |
---|---|---|
--w-color-black | Shadows only | |
--w-color-grey-800 | Backgrounds for panels in dark theme | |
--w-color-grey-700 | Backgrounds for panels in dark theme | |
--w-color-grey-600 | Body copy, user content | |
--w-color-grey-500 | Panels, dividers in dark mode | |
--w-color-grey-400 | Help text, placeholders, meta text, neutral state indicators | |
--w-color-grey-200 | Dividers, button borders | |
--w-color-grey-150 | Field borders | |
--w-color-grey-100 | Dividers, panel borders | |
--w-color-grey-50 | Background for panels, row highlights | |
--w-color-white | Page backgrounds, Panels, Button text | |
--w-color-primary | Wagtail branding, Panels, Headings, Buttons, Labels | |
--w-color-primary-200 | Accent for elements used in conjunction with primary colour in sidebar | |
--w-color-secondary | Primary buttons, action links | |
--w-color-secondary-600 | Hover states for two-tone buttons | |
--w-color-secondary-400 | Two-tone buttons, hover states | |
--w-color-secondary-100 | UI element highlights over dark backgrounds | |
--w-color-secondary-75 | UI element highlights over dark text | |
--w-color-secondary-50 | Button backgrounds, highlighted fields background | |
--w-color-info-125 | Hover background only, for information messages | |
--w-color-info-100 | Background and icons for information messages | |
--w-color-info-50 | Background only, for information messages | |
--w-color-positive-100 | Positive states | |
--w-color-positive-50 | Background only, for positive states | |
--w-color-warning-100 | Background and icons for potentially dangerous states | |
--w-color-warning-50 | Background only, for potentially dangerous states | |
--w-color-critical-200 | Dangerous actions or states (over light background), errors | |
--w-color-critical-100 | Dangerous actions or states (over dark background) | |
--w-color-critical-50 | Background only, for dangerous states |
Light & dark theme colours
Light | Dark | Variable |
---|---|---|
Surfaces - General | ||
--w-color-surface-page | ||
--w-color-surface-field | ||
--w-color-surface-field-inactive | ||
--w-color-surface-header | ||
--w-color-surface-menus | ||
--w-color-surface-menu-item-active | ||
--w-color-surface-tooltip | ||
--w-color-surface-button-default | ||
--w-color-surface-button-hover | ||
--w-color-surface-button-inactive | ||
--w-color-surface-button-outline-hover | ||
--w-color-surface-button-critical-hover | ||
Text | ||
--w-color-text-button | ||
--w-color-text-label-menus-default | ||
--w-color-text-label-menus-active | ||
--w-color-text-label | ||
--w-color-text-context | ||
--w-color-text-meta | ||
--w-color-text-placeholder | ||
--w-color-text-link-default | ||
--w-color-text-link-hover | ||
--w-color-text-button-outline-default | ||
--w-color-text-button-outline-hover | ||
--w-color-text-highlight | ||
--w-color-text-error | ||
--w-color-text-button-critical-outline-hover | ||
Icons | ||
--w-color-icon-primary | ||
--w-color-icon-primary-hover | ||
--w-color-icon-secondary | ||
--w-color-icon-secondary-hover | ||
Borders | ||
--w-color-border-furniture | ||
--w-color-border-button-small-outline-default | ||
--w-color-border-field-default | ||
--w-color-border-field-inactive | ||
--w-color-border-field-hover | ||
--w-color-border-button-outline-default | ||
--w-color-border-button-outline-hover | ||
Misc | ||
--w-color-focus | ||
--w-color-box-shadow-md |
Specifying a site or page in the branding¶
The admin interface has a number of variables available to the renderer context that can be used to customize the branding in the admin page. These can be useful for customizing the dashboard on a multi-tenanted Wagtail installation:
root_page
¶
Returns the highest explorable page object for the currently logged-in user. If the user has no explore rights, this will default to None
.
root_site
¶
Returns the name on the site record for the above root page.
site_name
¶
Returns the value of root_site
, unless it evaluates to None
. In that case, it will return the value of settings.WAGTAIL_SITE_NAME
.
To use these variables, create a template file dashboard/templates/wagtailadmin/home.html
, just as if you were overriding one of the template blocks in the dashboard, and use them as you would any other Django template variable:
{% extends "wagtailadmin/home.html" %}
{% block branding_welcome %}Welcome to the Admin Homepage for {{ root_site }}{% endblock %}
Extending the login form¶
To add extra controls to the login form, create a template file dashboard/templates/wagtailadmin/login.html
.
above_login
and below_login
¶
To add content above or below the login form, override these blocks:
{% extends "wagtailadmin/login.html" %}
{% block above_login %} If you are not Frank you should not be here! {% endblock %}
fields
¶
To add extra fields to the login form, override the fields
block. You will need to add {{ block.super }}
somewhere in your block to include the username and password fields:
{% extends "wagtailadmin/login.html" %}
{% block fields %}
{{ block.super }}
<li>
<div>
<label for="id_two-factor-auth">Two factor auth token</label>
<input type="text" name="two-factor-auth" id="id_two-factor-auth">
</div>
</li>
{% endblock %}
login_form
¶
To completely customize the login form, override the login_form
block. This block wraps the whole contents of the <form>
element:
{% extends "wagtailadmin/login.html" %}
{% block login_form %}
<p>Some extra form content</p>
{{ block.super }}
{% endblock %}
Extending the password reset request form¶
To add extra controls to the password reset form, create a template file dashboard/templates/wagtailadmin/account/password_reset/form.html
.
above_form
and below_form
¶
To add content above or below the password reset form, override these blocks:
{% extends "wagtailadmin/account/password_reset/form.html" %}
{% block above_login %} If you have not received your email within 7 days, call us. {% endblock %}
submit_buttons
¶
To add extra buttons to the password reset form, override the submit_buttons
block. You will need to add {{ block.super }}
somewhere in your block if you want to include the original submit button:
{% extends "wagtailadmin/account/password_reset/form.html" %}
{% block submit_buttons %}
<a href="{% url 'helpdesk' %}">Contact the helpdesk</a>
{% endblock %}
Extending client-side JavaScript¶
Wagtail provides multiple ways to extend client-side JavaScript.