Panel types

Built-in Fields and Choosers

Wagtail’s panel mechanism automatically recognises Django model fields and provides them with an appropriate widget for input. You can use it by defining the field in your Django model as normal and passing the field name into FieldPanel (or a suitable panel type) when defining your panels.

Here are some built-in panel types that you can use in your panel definitions. These are all subclasses of the base Panel class, and unless otherwise noted, they accept all of Panel’s parameters in addition to their own.


class wagtail.admin.panels.FieldPanel(field_name, widget=None, disable_comments=None, permission=None, **kwargs)

This is the panel to use for basic Django model field types. It provides a default icon and heading based on the model field definition, but they can be customised by passing additional arguments to the constructor. For more details, see Panel customisation.


This is the name of the class property used in your model definition.


This parameter allows you to specify a Django form widget to use instead of the default widget for this field type.


This allows you to prevent a field level comment button showing for this panel if set to True. See Create and edit comments.


Allows a field to be selectively shown to users with sufficient permission. Accepts a permission codename such as 'myapp.change_blog_category' - if the logged-in user does not have that permission, the field will be omitted from the form. See Django’s documentation on custom permissions for details on how to set permissions up; alternatively, if you want to set a field as only available to superusers, you can use any arbitrary string (such as 'superuser') as the codename, since superusers automatically pass all permission tests.


class wagtail.admin.panels.MultiFieldPanel(children=(), *args, permission=None, **kwargs)

This panel condenses several FieldPanel s or choosers, from a list or tuple, under a single heading string. To save space, you can collapse the panel by default.


A list or tuple of child panels


Allows a panel to be selectively shown to users with sufficient permission. Accepts a permission codename such as 'myapp.change_blog_category' - if the logged-in user does not have that permission, the panel will be omitted from the form. Similar to FieldPanel.permission.


class wagtail.admin.panels.InlinePanel(relation_name, panels=None, label='', min_num=None, max_num=None, **kwargs)

This panel allows for the creation of a “cluster” of related objects over a join to a separate model, such as a list of related links or slides to an image carousel. For a full explanation on the usage of InlinePanel, see Inline models. To save space, you can collapse the panel by default.


The related_name label given to the cluster’s ParentalKey relation.


The list of panels that will make up the child object’s form. If not specified here, the panels definition on the child model will be used.


Text for the add button and heading for child panels. Used as the heading when heading is not present.


Minimum number of forms a user must submit.


Maximum number of forms a user must submit.


New in version 4.2: The MultipleChooserPanel panel type was added.

class wagtail.admin.panels.MultipleChooserPanel(relation_name, chooser_field_name=None, panels=None, label='', min_num=None, max_num=None, **kwargs)

This is a variant of InlinePanel that improves the editing experience when the main feature of the child panel is a chooser for a ForeignKey relation (usually to an image, document, snippet or another page). Rather than the “Add” button inserting a new form to be filled in individually, it immediately opens up the chooser interface for that related object, in a mode that allows multiple items to be selected. The user is then returned to the main edit form with the appropriate number of child panels added and pre-filled.

MultipleChooserPanel accepts an additional required argument chooser_field_name, specifying the name of the ForeignKey relation that the chooser is linked to.

For example, given a child model that provies a gallery of images on BlogPage:

class BlogPageGalleryImage(Orderable):
    page = ParentalKey(BlogPage, on_delete=models.CASCADE, related_name='gallery_images')
    image = models.ForeignKey(
        'wagtailimages.Image', on_delete=models.CASCADE, related_name='+'
    caption = models.CharField(blank=True, max_length=250)

    panels = [

The MultipleChooserPanel definition on BlogPage would be:

            'gallery_images', label="Gallery images", chooser_field_name="image"


class wagtail.admin.panels.FieldRowPanel(children=(), *args, permission=None, **kwargs)

This panel creates a columnar layout in the editing interface, where each of the child Panels appears alongside each other rather than below.

Use of FieldRowPanel particularly helps reduce the “snow-blindness” effect of seeing so many fields on the page, for complex models. It also improves the perceived association between fields of a similar nature. For example if you created a model representing an “Event” which had a starting date and ending date, it may be intuitive to find the start and end date on the same “row”.

By default, the panel is divided into equal-width columns, but this can be overridden by adding col* class names to each of the child Panels of the FieldRowPanel. The Wagtail editing interface is laid out using a grid system. Classes col1-col12 can be applied to each child of a FieldRowPanel to define how many columns they span out of the total number of columns. When grid items add up to 12 columns, the class col3 will ensure that field appears 3 columns wide or a quarter the width. col4 would cause the field to be 4 columns wide, or a third the width.


A list or tuple of child panels to display on the row


Allows a panel to be selectively shown to users with sufficient permission. Accepts a permission codename such as 'myapp.change_blog_category' - if the logged-in user does not have that permission, the panel will be omitted from the form. Similar to FieldPanel.permission.


class wagtail.admin.panels.HelpPanel(content='', template='wagtailadmin/panels/help_panel.html', **kwargs)

A panel to display helpful information to the user.

This panel does not support the help_text parameter.


HTML string that gets displayed in the panel.


Path to a template rendering the full panel HTML.


class wagtail.admin.panels.PageChooserPanel(field_name, page_type=None, can_choose_root=False, **kwargs)

While FieldPanel also supports ForeignKey to Page models, you can explicitly use PageChooserPanel to allow Page-specific customisations.

from wagtail.models import Page
from wagtail.admin.panels import PageChooserPanel

class BookPage(Page):
    related_page = models.ForeignKey(

    content_panels = Page.content_panels + [
        PageChooserPanel('related_page', 'demo.PublisherPage'),

PageChooserPanel takes one required argument, the field name. Optionally, specifying a page type (in the form of an "appname.modelname" string) will filter the chooser to display only pages of that type. A list or tuple of page types can also be passed in, to allow choosing a page that matches any of those page types:

PageChooserPanel('related_page', ['demo.PublisherPage', 'demo.AuthorPage'])

Passing can_choose_root=True will allow the editor to choose the tree root as a page. Normally this would be undesirable, since the tree root is never a usable page, but in some specialised cases it may be appropriate; for example, a page with an automatic “related articles” feed could use a PageChooserPanel to select which subsection articles will be taken from, with the root corresponding to ‘everywhere’.


class wagtail.contrib.forms.panels.FormSubmissionsPanel(**kwargs)

This panel adds a single, read-only section in the edit interface for pages implementing the AbstractForm model. It includes the number of total submissions for the given form and also a link to the listing of submissions.

from wagtail.contrib.forms.models import AbstractForm
from wagtail.contrib.forms.panels import FormSubmissionsPanel

class ContactFormPage(AbstractForm):
    content_panels = [


class wagtail.admin.panels.TitleFieldPanel(*args, apply_if_live=False, classname='title', placeholder=True, targets=['slug'], **kwargs)

Prepares the default widget attributes that are used on Page title fields. Can be used outside of pages to easily enable the slug field sync functionality.

  • apply_if_live – (optional) If True, the built in slug sync behaviour will apply irrespective of the published state. The default is False, where the slug sync will only apply when the instance is not live (or does not have a live property).

  • classname – (optional) A CSS class name to add to the panel’s HTML element. Default is "title".

  • placeholder – (optional) If a value is provided, it will be used as the field’s placeholder, if False is provided no placeholder will be shown. If True, a placeholder value of "Title*" will be used or "Page Title*" if the model is a Page model. The default is True. If a widget is provided with a placeholder, the widget’s value will be used instead.

  • targets – (optional) This allows you to override the default target of the field named slug on the form. Accepts a list of field names, default is ["slug"]. Note that the slugify/urlify behaviour relies on usage of the wagtail.admin.widgets.slug widget on the slug field.

This is the panel to use for Page title fields or main titles on other models. It provides a default classname, placeholder and widget attributes to enable the automatic sync with the slug field in the form. Many of these defaults can be customised by passing additional arguments to the constructor. All the same FieldPanel arguments are supported including a custom widget. For more details, see Panel customisation.

Panel customisation

By adding extra parameters to your panel/field definitions, you can control much of how your fields will display in the Wagtail page editing interface. Wagtail’s page editing interface takes much of its behaviour from Django’s admin, so you may find many options for customisation covered there. (See Django model field reference).


Use the icon argument to the panel constructor to override the icon to be displayed next to the panel’s heading. For a list of available icons, see Available icons.


Use the heading argument to the panel constructor to set the panel’s heading. This will be used for the input’s label and displayed on the content minimap. If left unset for FieldPanels, it will be set automatically using the form field’s label (taken in turn from a model field’s verbose_name).

CSS classes

Use the classname argument to the panel constructor to add CSS classes to the panel. The class will be applied to the HTML <section> element of the panel. This can be used to add extra styling to the panel or to control its behaviour.

The title class can be used to make the input stand out with a bigger font size and weight.

The collapsed class will load the editor page with the panel collapsed under its heading.

    content_panels = [
            heading="Collection of Book Fields",

Help text

Use the help_text argument to the panel constructor to customise the help text to be displayed above the input. If unset for FieldPanels, it will be set automatically using the form field’s help_text (taken in turn from a model field’s help_text).

Placeholder text

By default, Wagtail uses the field’s label as placeholder text. To change it, pass to the FieldPanel a widget with a placeholder attribute set to your desired text. You can select widgets from Django’s form widgets, or any of the Wagtail’s widgets found in wagtail.admin.widgets.

For example, to customise placeholders for a Book snippet model:

from django import forms            # the default Django widgets live here
from wagtail.admin import widgets   # to use Wagtail's special datetime widget

class Book(models.Model):
    title = models.CharField(max_length=256)
    release_date = models.DateField()
    price = models.DecimalField(max_digits=5, decimal_places=2)

    # you can create them separately
    title_widget = forms.TextInput(
        attrs = {
            'placeholder': 'Enter Full Title'
    # using the correct widget for your field type and desired effect
    date_widget = widgets.AdminDateInput(
        attrs = {
            'placeholder': 'dd-mm-yyyy'

    panels = [
        FieldPanel('title', widget=title_widget), # then add them as a variable
        FieldPanel('release_date', widget=date_widget),
        FieldPanel('price', widget=forms.NumberInput(attrs={'placeholder': 'Retail price on release'})) # or directly inline

Required fields

To make input or chooser selection mandatory for a field, add blank=False to its model definition.

Hiding fields

Without a top-level panel definition, a FieldPanel will be constructed for each field in your model. If you intend to hide a field on the Wagtail page editor, define the field with editable=False. If a field is not present in the panels definition, it will also be hidden.