mirror of https://github.com/wagtail/wagtail.git synced 2024-11-28 08:48:04 +01:00

Sage Abdullah 3802f8bf46 Fix remaining XHTML errors in docs to remove ePub build errors

Had to remove the <details> element for the section linking example in
the "Reference links" section.

This is because Sphinx/MyST renders a <section> element for each heading
and closes it when the next heading starts. If we create a heading
inside a <details> element, the <section> element will not be closed
until the next heading starts, which generates invalid HTML.

2024-10-31 07:52:49 +10:00

3.1 KiB

Raw Blame History

(icons)=

Icons

Wagtail comes with an SVG icon set. The icons are used throughout the admin interface.

Elements that use icons are:

This document describes how to choose, add and customize icons.

Add a custom icon

Draw or download an icon and save it in a template folder:

# app/templates/app_name/toucan.svg

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 800" id="icon-toucan">
  <!--! CC0 license. https://creativecommons.org/publicdomain/zero/1.0/ -->
  <path d="M321 662v1a41 41 0 1 1-83-2V470c0-129 71-221 222-221 122 0 153-42 153-93 0-34-18-60-53-72v-4c147 23 203 146 203 257 0 107-80 247-277 247v79a41 41 0 1 1-82-1v46a41 41 0 0 1-83 0v-46Z"/>
  <path d="M555 136a23 23 0 1 0-46 0 23 23 0 0 0 46 0Zm-69-57H175c-60 0-137 36-137 145l9-8 367 6 72 18V79Z"/>
</svg>

The svg tag should:

Set the id="icon-<name>" attribute, icons are referenced by this name. The name should only contain lowercase letters, numbers, and hyphens.
Set the xmlns="http://www.w3.org/2000/svg" attribute.
Set the viewBox="..." attribute, and no width and height attributes.
If the icon should be mirrored in right-to-left (RTL) languages, set the class="icon--directional" attribute.
Include license / source information in a  HTML comment, if applicable.

Set fill="currentColor" or remove fill attributes so the icon color changes according to usage.

Add the icon with the register_icons hook.

@hooks.register("register_icons")
def register_icons(icons):
    return icons + ['app_name/toucan.svg']

The majority of Wagtail’s default icons are drawn on a 16x16 viewBox, sourced from the FontAwesome v6 free icons set.

Icon template tag

Use an icon in a custom template:

{% load wagtailadmin_tags %}
{% icon name="toucan" classname="..." title="..." %}

Changing icons via hooks

@hooks.register("register_icons")
def register_icons(icons):
    icons.remove("wagtailadmin/icons/time.svg")  # Remove the original icon
    icons.append("path/to/time.svg")  # Add the new icon
    return icons

Changing icons via template override

When several applications provide different versions of the same template, the application listed first in INSTALLED_APPS has precedence.

Place your app before any Wagtail apps in INSTALLED_APPS.

Wagtail icons live in wagtail/admin/templates/wagtailadmin/icons/. Place your own SVG files in <your_app>/templates/wagtailadmin/icons/.

(available_icons)=

Available icons

Enable the styleguide to view the available icons and their names for any given project.

Here are all available icons out of the box:

Toggle icons table

3.1 KiB Raw Blame History Unescape Escape