(ui_components)=

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.

```{include} ../../../client/README.md
:start-after: <!-- STABILITY:START -->
:end-before: <!-- STABILITY:END -->
```

Fragment

.. autofunction:: wagtail.admin.templatetags.wagtailadmin_tags.fragment

Dialog

.. class:: wagtail.admin.templatetags.wagtailadmin_tags.DialogNode
   :no-contents-entry:

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

.. function:: wagtail.admin.templatetags.wagtailadmin_tags.dialog_toggle
   :no-contents-entry:

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
   :no-contents-entry:

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.

Button with dropdown

.. class:: wagtail.admin.templatetags.wagtailadmin_tags.DropdownButtonNode
   :no-contents-entry:

A button with a dropdown menu next to it. This is a specialized version of the dropdown component. To create a button with dropdown, you need to combine a rendered button HTML fragment with the {% dropdown_button %} and {% enddropdown_button %} template tags.

{% load wagtailadmin_tags %}
{% fragment as button %}
    <button type="button" class="button">Main button</button>
{% endfragment %}
{% dropdown_button button=button toggle_icon="arrow-up" %}
    <button type="submit" class="button">First item</button>
    <a class="button" href="#">Second item</a>
{% enddropdown_button %}

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

Arguments for the {% dropdown_button %} tag:

• button: The main button HTML fragment.
• toggle_icon: Name of the icon to display on the toggle button. Defaults to arrow-down.
• toggle_classname: CSS classes for styling the toggle button.
• keep_mounted: Whether or not the dropdown should keep its DOM node mounted when hidden.
• classname: CSS classes for styling the element that wraps the button and dropdown.

Only the button argument is required, the rest are optional.

(ui_tooltip)=

Tooltip

A tooltip that can be attached to an HTML element to display additional information on hover or focus. It is powered by the TooltipController (w-tooltip). To add a tooltip, attach the w-tooltip controller to an element and specify the properties using data attributes.

<button
    type="button"
    data-controller="w-tooltip"
    data-w-tooltip-content-value="More detail here"
    data-w-tooltip-offset-value="[10, 15]"
    data-w-tooltip-placement-value="top"
>
  A button with a tooltip
</button>

If you need the tooltip to display rich content, you can use an HTML element as the content target with a data-w-tooltip-target="content" attribute inside the w-tooltip element:

<button
    type="button"
    data-controller="w-tooltip"
    data-w-tooltip-offset-value="[10, 15]"
    data-w-tooltip-placement-value="top"
>
  <template data-w-tooltip-target="content">
    More <strong>detail</strong> here
  </template>
  A button with a tooltip
</button>

Available value attributes for w-tooltip:

• data-w-tooltip-content-value: The content of the tooltip. Optional if a content target is used instead.
• data-w-tooltip-offset-value (optional): The offset of the tooltip from the element, specified as an array of two numbers ([skidding, distance]). Defaults to [0, 10].
• data-w-tooltip-placement-value (optional): The placement of the tooltip relative to the element. Possible values are top, top-start, top-end, right, right-start, right-end, bottom, bottom-start, bottom-end, left, left-start, left-end. Defaults to bottom.