ListPage

pageId

A unique identifier for the list page. This is important to support customization functionality that relies on page IDs and makes your component extensible.

route

• The TanStack Router Route object, which will be defined in the component file.

title

• The page title, which will display in the header area.

listQuery

This DocumentNode of the list query, i.e. a query that fetches PaginatedList data with "items" and "totalItems", such as:

Example

export const collectionListDocument = graphql(`  query CollectionList($options: CollectionListOptions) {    collections(options: $options) {      items {        id        createdAt        updatedAt        name        slug        breadcrumbs {          id          name          slug        }        children {          id          name        }        # ... etc      }      totalItems    }  }`);// ...<ListPage  pageId="collection-list"  listQuery={collectionListDocument}  // .../>

deleteMutation

Providing the deleteMutation will automatically add a "delete" menu item to the actions column dropdown. Note that if this table already has a "delete" bulk action, you don't need to additionally provide a delete mutation, because the bulk action will be added to the action column dropdown already.

transformVariables

This prop can be used to intercept and transform the list query variables before they are sent to the Admin API.

This allows you to implement specific logic that differs from the standard filter/sort handling.

Example

<ListPage  pageId="collection-list"  title="Collections"  listQuery={collectionListDocument}  transformVariables={input => {      const filterTerm = input.options?.filter?.name?.contains;      // If there is a filter term set      // we want to return all results. Else      // we only want top-level Collections      const isFiltering = !!filterTerm;      return {          options: {              ...input.options,              topLevelOnly: !isFiltering,          },      };  }}/>

onSearchTermChange

Allows you to customize how the search term is used in the list query options. For instance, when you want the term to filter on specific fields.

The returned filter is merged with the column & faceted filters, so when the term should match any of several fields, group those fields in an _or block. Setting a page-level filterOperator: 'OR' would instead OR together every top-level condition, including the column filters.

Example

<ListPage   pageId="administrator-list"   title="Administrators"   listQuery={administratorListDocument}   onSearchTermChange={searchTerm => {     return {       _or: [         { firstName: { contains: searchTerm } },         { lastName: { contains: searchTerm } },         { emailAddress: { contains: searchTerm } },       ],     };   }} />

searchPlaceholder

Placeholder text for the search input. Should say what the search targets, e.g. "Search products...". Defaults to a generic "Search...".

customizeColumns

Allows you to customize the rendering and other aspects of individual columns.

By default, an appropriate component will be chosen to render the column data based on the data type of the field. However, in many cases you want to have more control over how the column data is rendered.

Example

<ListPage  pageId="collection-list"  listQuery={collectionListDocument}  customizeColumns={{    // The key "name" matches one of the top-level fields of the    // list query type (Collection, in this example)    name: {      meta: {          // The Dashboard optimizes the list query `collectionListDocument` to          // only select field that are actually visible in the ListPage table.          // However, sometimes you want to render data from other fields, i.e.          // this column has a data dependency on the "children" and "breadcrumbs"          // fields in order to correctly render the "name" field.          // In this case, we can declare those data dependencies which means whenever          // the "name" column is visible, it will ensure the "children" and "breadcrumbs"          // fields are also selected in the query.          dependencies: ['children', 'breadcrumbs'],      },      header: 'Collection Name',      cell: ({ row }) => {        const isExpanded = row.getIsExpanded();        const hasChildren = !!row.original.children?.length;        return (          <div            style={{ marginLeft: (row.original.breadcrumbs?.length - 2) * 20 + 'px' }}            className="flex gap-2 items-center"          >            <Button              size="icon"              variant="secondary"              onClick={row.getToggleExpandedHandler()}              disabled={!hasChildren}              className={!hasChildren ? 'opacity-20' : ''}            >              {isExpanded ? <FolderOpen /> : <Folder />}            </Button>            <DetailPageButton id={row.original.id} label={row.original.name} />          </div>          );      },    },    // Use `meta.disabled` to completely exclude a column from the table,    // including the column visibility toggle. This is useful when you need    // to fetch certain fields for use in custom cell renderers, but don't    // want those fields to appear as their own columns.    productVariantCount: {      meta: { disabled: true },    },

additionalColumns

Allows you to define extra columns that are not related to actual fields returned in the query result.

For example, in the Administrator list, we define an additional "name" column composed of the firstName and lastName fields.

Example

<ListPage  pageId="administrator-list"  title="Administrators"  listQuery={administratorListDocument}  additionalColumns={{    name: {        header: 'Name',        cell: ({ row }) => (            <DetailPageButton                id={row.original.id}                label={`${row.original.firstName} ${row.original.lastName}`}            />        ),  },/>

defaultColumnOrder

Allows you to specify the default order of columns in the table. When not defined, the order of fields in the list query document will be used.

defaultSort

Allows you to specify the default sorting applied to the table.

Example

defaultSort={[{ id: 'updatedAt', desc: true }]}

defaultVisibility

Allows you to specify the default columns that are visible in the table. If you set them to true, then only those will show by default. If you set them to false, then all other columns will be visible by default.

Example

<ListPage   pageId="country-list"   listQuery={countriesListQuery}   title="Countries"   defaultVisibility={{       name: true,       code: true,       enabled: true,   }} />

children

dropdownMenuItems

Optional dropdown menu items to display in the action bar's overflow (⋮) menu. These are forwarded to the PageActionBar.

facetedFilters

Allows you to define pre-set filters based on an array of possible selections

Example

<ListPage  pageId="payment-method-list"  listQuery={paymentMethodListQuery}  title="Payment Methods"  facetedFilters={{      enabled: {          title: 'Enabled',          options: [              { label: 'Enabled', value: true },              { label: 'Disabled', value: false },          ],      },  }}/>

rowActions

Allows you to specify additional "actions" that will be made available in the "actions" column. By default, the actions column includes all bulk actions defined in the bulkActions prop.

transformData

Allows the returned list query data to be transformed in some way. This is an advanced feature that is not often required.

transformQueryKey

Allows the react-query cache key to be transformed. Use this together with the transformVariables prop when a page injects extra state into the query (e.g. a language selector or a status filter): the default key only reflects page, sorting, column filters and the search term, so without transforming the key too, changing the injected state serves a stale cached result instead of refetching.

disableViewOptions

When true, disables the view options (column visibility) control in the table toolbar.

includeSelectionColumn

When false, the row selection checkbox column will not be included.

setTableOptions

Allows you to directly manipulate the TanStack Table TableOptions object before the table is created. And advanced option that is not often required.

bulkActions

Bulk actions are actions that can be applied to one or more table rows, and include things like

• Deleting the rows
• Assigning the rows to another channel
• Bulk editing some aspect of the rows

See the BulkAction docs for an example of how to build the component.

Example

<ListPage  pageId="product-list"  listQuery={productListDocument}  title="Products"  bulkActions={[    {      component: AssignProductsToChannelBulkAction,      order: 100,    },    {      component: RemoveProductsFromChannelBulkAction,      order: 200,    },    {      component: DeleteProductsBulkAction,      order: 300,    },  ]}/>

registerRefresher

Register a function that allows you to assign a refresh function for this list. The function can be assigned to a ref and then called when the list needs to be refreshed.

onReorder

Callback when items are reordered via drag and drop. Only applies to top-level items. When provided, enables drag-and-drop functionality.

disableDragAndDrop

When true, drag and drop will be disabled. This will only have an effect if the onReorder prop is also set Useful when filtering or searching. Defaults to false. Only relevant when onReorder is provided.

emptyStateAction

An optional action rendered inside the first-run empty state (when the list has no items and no active filters), typically a "create your first X" CTA. Gate it with a PermissionGuard to mirror the create button's permissions.

emptyStateIllustration

An optional illustration rendered in the first-run empty state (no data and no active filters). Defaults to the generic empty-collection illustration. Pass a scenario illustration such as NoProductsIllustration when one matches.