Panel API

This document describes the reference API for the base Panel and the BoundPanel classes that are used to render Wagtail’s panels. For available panel types and how to use them, see Panel types.


class wagtail.admin.panels.Panel(heading='', classname='', help_text='', base_form_class=None, icon='', attrs=None)

Defines part (or all) of the edit form interface for pages and other models within the Wagtail admin. Each model has an associated top-level panel definition (also known as an edit handler), consisting of a nested structure of Panel objects. This provides methods for obtaining a ModelForm subclass, with the field list and other parameters collated from all panels in the structure. It then handles rendering that form as HTML.

The following parameters can be used to customise how the panel is displayed. For more details, see Panel customization.

  • heading – The heading text to display for the panel.

  • classname – A CSS class name to add to the panel’s HTML element.

  • help_text – Help text to display within the panel.

  • base_form_class – The base form class to use for the panel. Defaults to the model’s base_form_class, before falling back to WagtailAdminModelForm. This is only relevant for the top-level panel.

  • icon – The name of the icon to display next to the panel heading.

  • attrs – A dictionary of HTML attributes to add to the panel’s HTML element.


Create a clone of this panel definition with a model attribute pointing to the linked model class.


Called after the panel has been associated with a model class and the self.model attribute is available; panels can override this method to perform additional initialisation related to the model.


Create a clone of this panel definition. By default, constructs a new instance, passing the keyword arguments returned by clone_kwargs.


Return a dictionary of keyword arguments that can be used to create a clone of this panel definition.


Return a dictionary of attributes such as ‘fields’, ‘formsets’ and ‘widgets’ which should be incorporated into the form class definition to generate a form that this panel can use. This will only be called after binding to a model (i.e. self.model is available).


Construct a form class that has all the fields and formsets named in the children of this edit handler.

get_bound_panel(instance=None, request=None, form=None, prefix='panel')

Return a BoundPanel instance that can be rendered onto the template as a component. By default, this creates an instance of the panel class’s inner BoundPanel class, which must inherit from Panel.BoundPanel.

property clean_name

A name for this panel, consisting only of ASCII alphanumerics and underscores, suitable for use in identifiers. Usually generated from the panel heading. Note that this is not guaranteed to be unique or non-empty; anything making use of this and requiring uniqueness should validate and modify the return value as needed.


class wagtail.admin.panels.Panel.BoundPanel(panel, instance, request, form, prefix)

A template component for a panel that has been associated with a model instance, form, and request.

In addition to the standard template component functionality (see Creating components), this provides the following attributes and methods:


The panel definition corresponding to this bound panel


The model instance associated with this panel


The request object associated with this panel


The form object associated with this panel


A unique prefix for this panel, for use in HTML IDs


Returns an HTML ID to be used as the target for any label referencing this panel.


Whether this panel should be rendered; if false, it is skipped in the template output.