# Tables

Wagtail provides a set of base table components that can be used to build tables in the Wagtail admin.
For more details on how to use these components, refer to the documentation for customizing [generic listings](../../extending/generic_views.md#modelviewset-listing) and [page listings](../../advanced_topics/customization/custom_page_listings.md#custom-page-listings).

## Base table components

These are the basic building blocks for constructing tables in the Wagtail admin.

### *class* wagtail.admin.ui.tables.BaseColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

A column that encapsulates the header and data cells for rendering.

* **Parameters:**
  * **name** – The internal name of the column, used to identify it within the table.
  * **label** – The human-readable label for the column header.
    If not provided, a label will be generated from the name.
  * **accessor** – A dotted path to an attribute accessed from the current
    row’s object, or a callable that takes the current row’s object, that
    returns the value for this column. This is unused by default, but may be
    used by subclasses such as [`Column`](#wagtail.admin.ui.tables.Column).
  * **classname** – Optional CSS classes to apply to all cells in this column.
  * **sort_key** – An optional key for a query parameter that identifies the
    field by which the table can be sorted when this column’s header is
    clicked. If not provided, the column will not be sortable.
  * **width** – An optional width for the column.
  * **ascending_title_text** – An optional text for the column header’s
    `title` attribute when the column is sorted in ascending order. If not
    provided, a default string will be used that incorporates the column label.
  * **descending_title_text** – An optional text for the column header’s
    `title` attribute when the column is sorted in descending order. If not
    provided, a default string will be used that incorporates the column label.

#### get_cell(instance)

Returns an object encapsulating this column and an item of data, which we can use for
rendering a table cell into a template.

#### get_cell_context_data(instance, parent_context)

Compiles the context dictionary to pass to the cell template when rendering a table cell for
the given instance.

#### get_header_context_data(parent_context)

Compiles the context dictionary to pass to the header template when rendering the column header.

#### render_cell_html(instance, parent_context)

Renders a table cell containing data for the given instance.

#### render_header_html(parent_context)

Renders the column’s header.

#### cell_template_name *= None*

The name of the template used to render a cell of this column.

#### header_template_name *= 'wagtailadmin/tables/column_header.html'*

The name of the template used to render the column header.

### *class* wagtail.admin.ui.tables.Column(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`BaseColumn`](#wagtail.admin.ui.tables.BaseColumn)

A column that displays a single field of data from the model.

#### get_cell_context_data(instance, parent_context)

Compiles the context dictionary to pass to the cell template when rendering a table cell for
the given instance.

#### get_value(instance)

Given an instance (i.e. any object containing data), extracts the field
of data to be displayed in a cell of this column. By default, this uses
the `accessor` to retrieve the value.

#### cell_template_name *= 'wagtailadmin/tables/cell.html'*

The name of the template used to render a cell of this column.

#### empty_value_display *= ''*

The text to display in cells where the value is empty.

### *class* wagtail.admin.ui.tables.Table(columns, data, template_name=None, base_url=None, ordering=None, classname=None, attrs=None, caption=None)

Bases: [`Component`](../../extending/template_components.md#wagtail.admin.ui.components.Component)

A component that renders a table.

* **Parameters:**
  * **columns** – An iterable of [`Column`](#wagtail.admin.ui.tables.Column) objects representing the
    columns of the table.
  * **data** – An iterable of objects representing the rows of the table. Each
    object will be passed to the columns to extract the data for each cell.
  * **template_name** – An optional name of the template used to render the
    table. If not provided, a default template will be used.
  * **base_url** – An optional base URL to use for constructing sorting links
    in the column headers.
  * **ordering** – An optional string representing the current ordering of the
    table, used to determine the state of the sorting links in the column
    headers. This should match the sort_key of one of the columns,
    optionally prefixed with “-” to indicate descending order.
  * **classname** – Optional CSS classes to apply to the `<table>` element.
  * **attrs** – An optional dictionary of additional HTML attributes to apply
    to the `<table>` element.
  * **caption** – An optional caption for the table.

#### get_context_data(parent_context)

Return the context data to render this component with.

## Column types

These are the various column types provided by Wagtail that can be used within tables that list any type of objects.
They are all subclasses of [`BaseColumn`](#wagtail.admin.ui.tables.BaseColumn) and can be used directly or subclassed to create new column types.

### *class* wagtail.admin.ui.tables.BooleanColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays a `True`/`False`/`None` value as a
tick/cross/question icon.

### *class* wagtail.admin.ui.tables.BulkActionsCheckboxColumn(\*args, obj_type, \*\*kwargs)

Bases: [`BaseColumn`](#wagtail.admin.ui.tables.BaseColumn)

A checkbox column for the bulk actions feature.

When using this column, there should be another column (such as a [`TitleColumn`](#wagtail.admin.ui.tables.TitleColumn))
that has an element with the id `{obj_type}_{instance.pk}_title` that contains
the title of the object (and nothing else) for screen reader purposes.

* **Parameters:**
  **obj_type** – A string representing the type of object being listed, used
  to construct the `aria-describedby` attribute for the checkboxes.

### *class* wagtail.admin.ui.tables.DateColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays a date in human-readable format.

### *class* wagtail.admin.ui.tables.DownloadColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays the object’s `url` property as a link to download
a file.

### *class* wagtail.admin.ui.tables.LiveStatusTagColumn(\*\*kwargs)

Bases: [`StatusTagColumn`](#wagtail.admin.ui.tables.StatusTagColumn)

A column that displays a live/draft status tag.

### *class* wagtail.admin.ui.tables.LocaleColumn(\*\*kwargs)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays a [`Locale`](../models.md#wagtail.models.Locale) label.

### *class* wagtail.admin.ui.tables.NumberColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A specialized column that displays numbers with locale-aware formatting.

### *class* wagtail.admin.ui.tables.orderable.OrderingColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`BaseColumn`](#wagtail.admin.ui.tables.BaseColumn)

A column that displays a reordering control for each row.

### *class* wagtail.admin.ui.tables.ReferencesColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, get_url=None, describe_on_delete=False)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays references that were extracted from the current row’s
object.

* **Parameters:**
  * **get_url** – An optional callable that takes the current row’s object and
    returns the URL to link to. If not provided, the references will be
    displayed without a link.
  * **describe_on_delete** – An optional boolean that determines whether to
    display a description of the reference’s `on_delete` behavior. Useful
    when confirming deletion of an object that has references to it, so the
    user can understand the consequences of deleting the object.

### *class* wagtail.admin.ui.tables.RelatedObjectsColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays a list of objects related to the object through a
one-to-many relationship.

### *class* wagtail.admin.ui.tables.StatusFlagColumn(name, true_label=None, false_label=None, \*\*kwargs)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays a boolean value as a status tag (or lack thereof,
if the corresponding label is `None`).

* **Parameters:**
  * **true_label** – The string to display when the value is `True`.
  * **false_label** – The string to display when the value is `False`.

### *class* wagtail.admin.ui.tables.StatusTagColumn(name, primary=None, \*\*kwargs)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays a status tag.

* **Parameters:**
  **primary** – An optional boolean or callable that takes the current row’s
  object and returns a boolean, indicating whether the status tag should
  be styled as “primary”.

### *class* wagtail.admin.ui.tables.TitleColumn(name, url_name=None, get_url=None, get_title_id=None, label_prefix=None, get_label_id=None, link_classname=None, link_attrs=None, id_accessor='pk', \*\*kwargs)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays a title wrapped in a link (`<a>`) or `<label>`.
The cell’s template has the ability to render action buttons.

* **Parameters:**
  * **url_name** – An optional URL pattern name to use for constructing the
    link URL for each cell in this column.
  * **get_url** – An optional callable that takes the current row’s object and
    returns the URL to link to for that row. If both this and `url_name`
    are provided, this takes precedence.
  * **get_title_id** – An optional callable that takes the current row’s
    object and returns a string to use as the id attribute for an element
    that contains the object’s title, such as `"page_{obj.pk}_title"`.
    This can be used by other columns (such as
    [`BulkActionsCheckboxColumn`](#wagtail.admin.ui.tables.BulkActionsCheckboxColumn)) for screen reader purposes.
  * **label_prefix** – An optional string prefix to use for constructing the
    `for` attribute when the title is rendered as a `<label>`. The id of
    the corresponding input element must be in the format of
    `"{label_prefix}-{id}"`.
  * **get_label_id** – An optional callable that takes the current row’s
    object and returns a string to use as the `for` attribute when the
    title is rendered as a `<label>`. If both this and `label_prefix`
    are provided, this takes precedence.
  * **link_classname** – An optional string of CSS classes to apply to the
    `<a>` element when the title is wrapped in a link.
  * **link_attrs** – An optional dictionary of additional HTML attributes to
    apply to the `<a>` element when the title is wrapped in a link.
  * **id_accessor** – An optional dotted path to an attribute accessed from
    the current row’s object, that returns the value to use as the id when
    constructing URLs or label attributes. Defaults to `"pk"`.

### *class* wagtail.admin.ui.tables.UpdatedAtColumn(\*\*kwargs)

Bases: [`DateColumn`](#wagtail.admin.ui.tables.DateColumn)

A column that displays the `_updated_at` date annotation in
human-readable format.

### *class* wagtail.admin.ui.tables.UsageCountColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays the number of times an object has been referenced.

### *class* wagtail.admin.ui.tables.UserColumn(name, blank_display_name='', \*\*kwargs)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays the username and avatar for a user.

* **Parameters:**
  **blank_display_name** – The text to display when the user’s name is empty.

## Page-specific table components

These are table components that are specific to page listings in the Wagtail admin.

### *class* wagtail.admin.ui.tables.pages.PageTitleColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`BaseColumn`](#wagtail.admin.ui.tables.BaseColumn)

A column that displays the title of a page with indicators for site root,
locale, lock status, and privacy restrictions, as well as additional context
such as the parent page and result scope when the results have been filtered
or searched.

### *class* wagtail.admin.ui.tables.pages.ParentPageColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays the parent page of a given page. It uses a
`_parent_page` annotation if present on the page instance for efficiency,
before falling back to calling  [`get_parent()`](../models.md#wagtail.models.Page.get_parent).

### *class* wagtail.admin.ui.tables.pages.BulkActionsColumn(\*args, \*\*kwargs)

Bases: [`BulkActionsCheckboxColumn`](#wagtail.admin.ui.tables.BulkActionsCheckboxColumn)

A page-specific version of
[`BulkActionsCheckboxColumn`](#wagtail.admin.ui.tables.BulkActionsCheckboxColumn) that is aware
of the parent page instance.

### *class* wagtail.admin.ui.tables.pages.PageTypeColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`Column`](#wagtail.admin.ui.tables.Column)

A column that displays the page’s content type.

### *class* wagtail.admin.ui.tables.pages.NavigateToChildrenColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)

Bases: [`BaseColumn`](#wagtail.admin.ui.tables.BaseColumn)

A column that provides a link to explore the child pages of a page.

### *class* wagtail.admin.ui.tables.pages.PageTable(\*args, parent_page=None, show_locale_labels=False, actions_next_url=None, \*\*kwargs)

Bases: [`OrderableTableMixin`](#wagtail.admin.ui.tables.orderable.OrderableTableMixin), [`Table`](#wagtail.admin.ui.tables.Table)

A page-specific version of [`Table`](#wagtail.admin.ui.tables.Table) that
supports reordering and supplies additional information to the context.

## Supporting components

These are additional components that can be used to enhance the functionality of tables in the Wagtail admin, such as adding buttons or making tables orderable.

### *class* wagtail.admin.ui.tables.ButtonsColumnMixin

Bases: [`object`](https://docs.python.org/3/library/functions.html#object)

A mixin for columns that contain buttons. The column’s template should
iterate over the `buttons` variable in the context to render them.

#### get_buttons(instance, parent_context)

Returns a list of button components to be supplied as `buttons` in the
template context.

#### buttons *= []*

A list of button components.

### *class* wagtail.admin.ui.tables.orderable.OrderableTableMixin(\*args, sort_order_field=None, reorder_url=None, \*\*kwargs)

Bases: [`object`](https://docs.python.org/3/library/functions.html#object)

A mixin class that adds a reordering functionality to a table.