# 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](../../contributing/ui_guidelines.md#styleguide) and the [pattern library](../../contributing/ui_guidelines.md#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: ```html+django {% 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](https://mitchel.me/slippers/docs/template-tags-filters/#fragment) 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): ```html+django {% 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 `
` and ``.

## Dialog

#### *class* wagtail.admin.templatetags.wagtailadmin_tags.DialogNode

A dialog to display information in a modal dialog. It is powered by the [`DialogController`](/en/13830/reference/ui/client/classes/controllers_DialogController.DialogController.html#) (`w-dialog`). To create a dialog, you can use the `{% dialog %}` and `{% enddialog %}` template tags.

```html+django
{% 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" %}
    
This dialog message was generated by passing message_status=critical as well as message_heading and message_description to the dialog template tag

{% enddialog %}
```

Required arguments for the `{% dialog %}` tag:

- `id`: The ID of the dialog, to be used by the [`{% dialog_toggle %}`](#wagtail.admin.templatetags.wagtailadmin_tags.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 `
` 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.

```html+django
{% 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`](/en/13830/reference/ui/client/classes/controllers_DropdownController.DropdownController.html#) (`w-dropdown`). To create a dropdown, you can use the `{% dropdown %}` and `{% enddropdown %}` template tags.

```html+django
{% dropdown toggle_icon="dots-horizontal" toggle_aria_label="Actions" %}
    {% icon name="arrow-right-full" %} Move
    {% icon name="copy" %} Copy
    {% icon name="bin" %} Delete
    {% icon name="download" %} Unpublish
{% 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](#ui-tooltip).
- `toggle_tippy_offset`: The offset value for the dropdown toggle’s [Tooltip](#ui-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

A button with a dropdown menu next to it. This is a specialized version of the [dropdown](#wagtail.admin.templatetags.wagtailadmin_tags.DropdownNode) 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.

```html+django
{% load wagtailadmin_tags %}
{% fragment as button %}
    
{% endfragment %}
{% dropdown_button button=button toggle_icon="arrow-up" %}
    
    Second item
{% 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.



## 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`](/en/13830/reference/ui/client/classes/controllers_TooltipController.TooltipController.html#) (`w-tooltip`). To add a tooltip, attach the `w-tooltip` controller to an element and specify the properties using data attributes.

```html

```

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:

```html

```

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`.