UI components¶

This document provides a reference for Wagtail’s user interface (UI) components, which are used to build the features within the CMS. A demonstration of these components are available through the Styleguide app and the pattern library.

Note

We provide documentation for these components without making them subject to the same stability guarantees outlined in our deprecation policy. This means a component’s API may change in a minor release without going through the deprecation process. If you use these components in your own code, please ensure that you have a testing process in place to catch any breaking changes with each Wagtail upgrade.

Fragment¶

wagtail.admin.templatetags.wagtailadmin_tags.fragment(parser, token)¶

Store a template fragment as a variable.

Usage:

{% fragment as header_title %}
    {% blocktrans trimmed %}Welcome to the {{ site_name }} Wagtail CMS{% endblocktrans %}
{% endfragment %}
{% include "my/custom/header.html" with title=header_title %}

Adopted from slippers’ fragment template tag with a few tweaks.

To strip leading and trailing whitespace produced in the fragment, use the stripped option. This is useful if you need to check if the resulting fragment is empty (after leading and trailing spaces are removed):

{% fragment stripped as recipient %}
    {{ title }} {{ first_name }} {{ last_name }}
{% endfragment %}
{% if recipient %}
    Recipient: {{ recipient }}
{% endif %}

Note that the stripped option only strips leading and trailing spaces, unlike {% blocktrans trimmed %} that also does line-by-line stripping. This is because the fragment may contain HTML tags that are sensitive to whitespace, such as <pre> and <code>.

Dialog¶

class wagtail.admin.templatetags.wagtailadmin_tags.DialogNode¶

A dialog to display information in a modal dialog. It is powered by the DialogController (w-dialog). To create a dialog, you can use the {% dialog %} and {% enddialog %} template tags.

{% dialog icon_name="globe" title="Dialog with critical error" id="my-dialog" subtitle="This is a testing subtitle" message_status="critical" message_heading="There was an issue with the thing" message_description="This is a subtext for the message" %}
    <p>This dialog message was generated by passing message_status=critical as well as message_heading and message_description to the dialog template tag</p>
{% enddialog %}

Required arguments for the {% dialog %} tag:

id: The ID of the dialog, to be used by the {% dialog_toggle %} tag.
title: The title of the dialog.

Optional arguments for the {% dialog %} tag:

dialog_root_selector: The CSS selector for the dialog root element, defaults to body. Useful when you want to render the dialog in a specific part of the DOM, such as within a <form> element.
icon_name: The name of the icon to display in the dialog header.
subtitle: The subtitle of the dialog.
theme: The theme of the dialog, either empty or floating.
classname: CSS classes for styling the dialog.

The content of the dialog can be any Django template code written between the {% dialog %} and {% enddialog %} tags.

The dialog can also display a status message at the top, such as an error or a warning. The following optional arguments can be used to render the message:

message_status: The status level of the message, which can be one of: info, warning, critical, success.
message_heading: The heading of the message.
message_description: The description of the message.

Dialog toggle¶

wagtail.admin.templatetags.wagtailadmin_tags.dialog_toggle()¶

A button component that opens a dialog with the specified ID. To create a button that opens a dialog, you can use the {% dialog_toggle %} template tag.

{% dialog_toggle classname='button' dialog_id='my-dialog' text='Dialog with error' %}

Arguments for the {% dialog_toggle %} tag:

dialog_id: The ID of the dialog to open.
text: The text to display on the button.
classname (optional): CSS classes for styling the button.

Dropdown¶

class wagtail.admin.templatetags.wagtailadmin_tags.DropdownNode¶

A dropdown menu to display a list of actions or options. It is powered by the DropdownController (w-dropdown). To create a dropdown, you can use the {% dropdown %} and {% enddropdown %} template tags.

{% dropdown toggle_icon="dots-horizontal" toggle_aria_label="Actions" %}
    <a href="/admin/pages/2/move/">{% icon name="arrow-right-full" %} Move</a>
    <a href="/admin/pages/2/copy/">{% icon name="copy" %} Copy</a>
    <a href="/admin/pages/2/delete/">{% icon name="bin" %} Delete</a>
    <a href="/admin/pages/2/unpublish/">{% icon name="download" %} Unpublish</a>
{% enddropdown %}

The dropdown’s contents must be a and button elements only.

Arguments for the {% dropdown %} tag:

toggle_icon: Name of the icon to display on the toggle button.
toggle_label: Visible label for the toggle button, displayed before the icon.
toggle_suffix: Visible content for the toggle button, displayed after the icon.
toggle_aria_label: aria-label for the toggle button.
toggle_describedby: aria-describedby for the toggle button.
toggle_classname: CSS classes for styling the toggle button.
toggle_tooltip_offset: The offset value for the dropdown, in similar format to the offset of Tooltip.
toggle_tippy_offset: The offset value for the dropdown toggle’s Tooltip.
hide_on_click: Whether or not the dropdown should hide when clicking inside its content.
keep_mounted Whether or not the dropdown should keep its DOM node mounted when hidden.
classname: CSS classes for styling the dropdown.
attrs: HTML attributes to add to the dropdown element.

All of the above arguments are optional, but either toggle_label or a combination of toggle_icon and toggle_aria_label must be provided to ensure the dropdown toggle is accessible.