Support documented ability to override/extend icons in the userbar

Allow to override icons in userbar

CHANGELOG.txt

@@ -13,6 +13,7 @@ Changelog
  * Add color-scheme meta tag to Wagtail admin (Ashish Nagmoti)
  * Add the ability to set the default privacy restriction for new pages using `get_default_privacy_setting` (Shlomo Markowitz)
  * Improve performance of batch purging page urls in the frontend cache, avoiding n+1 query issues (Andy Babic)
+ * Add better support and documentation for overriding or extending icons used in the in the userbar (Sébastien Corbin)
  * Fix: Take preferred language into account for translatable strings in client-side code (Bernhard Bliem, Sage Abdullah)
  * Fix: Do not show the content type column as sortable when searching pages (Srishti Jaiswal, Sage Abdullah)
  * Fix: Support simple subqueries for `in` and `exact` lookup on Elasticsearch (Sage Abdullah)

docs/advanced_topics/icons.md

@@ -76,6 +76,22 @@ 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/`.
 
+(custom_icons_userbar)=
+
+### Using custom icons in the userbar
+
+The userbar provides quick actions within page views when logged in. To customize the items shown in the user bar, you can use the [`construct_wagtail_userbar`](construct_wagtail_userbar) hook. If you want to use custom icons within these menu items they must be made available in the correct template.
+
+```html+django
+{# <yourapp>/templates/wagtailadmin/userbar/base.html #}
+{% extends "wagtailadmin/userbar/base.html" %}
+
+{% block icons %}
+    {{ block.super }}
+    {% include "wagtailadmin/icons/toucan.svg" %}
+{% endblock %}
+```
+
 (available_icons)=
 
 ## Available icons

docs/reference/hooks.md

@@ -885,6 +885,8 @@ def add_puppy_link_item(request, items, page):
     return items.append( UserbarPuppyLinkItem() )
 ```
 
+If you intend to use icons in your actions, you'll have to declare them by overriding the [userbar template](custom_icons_userbar).
+
 ## Admin workflow
 
 Hooks for customizing the way admins are directed through the process of editing users.

docs/releases/6.5.md

@@ -25,6 +25,7 @@ This version adds formal support for Django 5.2.
  * Add color-scheme meta tag to Wagtail admin (Ashish Nagmoti)
  * Add the ability to set the [default privacy restriction for new pages](set_default_page_privacy) using `get_default_privacy_setting` (Shlomo Markowitz)
  * Improve performance of batch purging page urls in the frontend cache, avoiding n+1 query issues (Andy Babic)
+ * Add better support and documentation for overriding or extending [icons used in the in the userbar](custom_icons_userbar) (Sébastien Corbin)
 
 ### Bug fixes
 

wagtail/admin/templates/wagtailadmin/userbar/base.html

@@ -10,14 +10,16 @@
 
                 <svg class="w-hidden">
                     <defs>
-                        {% include "wagtailadmin/icons/wagtail.svg" %}
-                        {% include "wagtailadmin/icons/key.svg" %}
-                        {% include "wagtailadmin/icons/folder-open-inverse.svg" %}
-                        {% include "wagtailadmin/icons/edit.svg" %}
-                        {% include "wagtailadmin/icons/plus.svg" %}
-                        {% include "wagtailadmin/icons/check.svg" %}
-                        {% include "wagtailadmin/icons/cross.svg" %}
-                        {% include "wagtailadmin/icons/crosshairs.svg" %}
+                        {% block icons %}
+                            {% include "wagtailadmin/icons/wagtail.svg" %}
+                            {% include "wagtailadmin/icons/key.svg" %}
+                            {% include "wagtailadmin/icons/folder-open-inverse.svg" %}
+                            {% include "wagtailadmin/icons/edit.svg" %}
+                            {% include "wagtailadmin/icons/plus.svg" %}
+                            {% include "wagtailadmin/icons/check.svg" %}
+                            {% include "wagtailadmin/icons/cross.svg" %}
+                            {% include "wagtailadmin/icons/crosshairs.svg" %}
+                        {% endblock %}
                     </defs>
                 </svg>