ListPage

Auto-generates a list page with columns generated based on the provided query document fields.

Example

Tsx

import {    Button,    DashboardRouteDefinition,    ListPage,    PageActionBarRight,    DetailPageButton,} from '@vendure/dashboard';import { Link } from '@tanstack/react-router';import { PlusIcon } from 'lucide-react';// This function is generated for you by the `vendureDashboardPlugin` in your Vite config.// It uses gql-tada to generate TypeScript types which give you type safety as you write// your queries and mutations.import { graphql } from '@/gql';// The fields you select here will be automatically used to generate the appropriate columns in the// data table below.const getArticleList = graphql(`    query GetArticles($options: ArticleListOptions) {        articles(options: $options) {            items {                id                createdAt                updatedAt                isPublished                title                slug                body                customFields            }            totalItems        }    }`);const deleteArticleDocument = graphql(`    mutation DeleteArticle($id: ID!) {        deleteArticle(id: $id) {            result        }    }`);export const articleList: DashboardRouteDefinition = {    navMenuItem: {        sectionId: 'catalog',        id: 'articles',        url: '/articles',        title: 'CMS Articles',    },    path: '/articles',    loader: () => ({        breadcrumb: 'Articles',    }),    component: route => (        <ListPage            pageId="article-list"            title="Articles"            listQuery={getArticleList}            deleteMutation={deleteArticleDocument}            route={route}            customizeColumns={{                title: {                    cell: ({ row }) => {                        const post = row.original;                        return <DetailPageButton id={post.id} label={post.title} />;                    },                },            }}        >            <PageActionBarRight>                <Button render={<Link to="./new" />}>                    <PlusIcon className="mr-2 h-4 w-4" />                    New article                </Button>            </PageActionBarRight>        </ListPage>    ),};

Signature

function ListPage<T extends TypedDocumentNode<U, V>, U extends Record<string, any> = any, V extends ListQueryOptionsShape = ListQueryOptionsShape, AC extends AdditionalColumns<T> = AdditionalColumns<T>>(props: Readonly<ListPageProps<T, U, V, AC>>): void

Parameters

props

parameterReadonly<ListPageProps<T, U, V, AC>>

ListPageProps

@vendure/dashboard Sourcev3.3.0

Props to configure the ListPage component.

Signature

interface ListPageProps<T extends TypedDocumentNode<U, V>, U extends ListQueryShape, V extends ListQueryOptionsShape, AC extends AdditionalColumns<T>> {    pageId?: string;    route: AnyRoute | (() => AnyRoute);    title: string | React.ReactElement;    listQuery: T;    deleteMutation?: TypedDocumentNode<any, { id: string }>;    transformVariables?: (variables: V) => V;    onSearchTermChange?: (searchTerm: string) => NonNullable<V['options']>['filter'];    customizeColumns?: CustomizeColumnConfig<T>;    additionalColumns?: AC;    defaultColumnOrder?: (keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>)[];    defaultSort?: SortingState;    defaultVisibility?: Partial<        Record<keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>, boolean>    >;    children?: React.ReactNode;    facetedFilters?: FacetedFilterConfig<T>;    rowActions?: RowAction<ListQueryFields<T>>[];    transformData?: (data: any[]) => any[];    setTableOptions?: (table: TableOptions<any>) => TableOptions<any>;    bulkActions?: BulkActionsInput;    registerRefresher?: PaginatedListRefresherRegisterFn;    onReorder?: (oldIndex: number, newIndex: number, item: any) => void | Promise<void>;    disableDragAndDrop?: boolean;}

pageId

propertystring

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

propertyAnyRoute | (() => AnyRoute)

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

title

propertystring | React.ReactElement

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

listQuery

propertyT

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

Example

Tsx

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

propertyTypedDocumentNode<any, { id: string }>

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

property(variables: V) => V

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

Tsx

<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

property(searchTerm: string) => NonNullable<V['options']>['filter']

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.

Example

Tsx

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

customizeColumns

propertyCustomizeColumnConfig<T>

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

Tsx

<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

propertyAC

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

Tsx

<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

property(keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>)[]

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

propertySortingState

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

Example

Tsx

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

defaultVisibility

propertyPartial< Record<keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>, boolean> >

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

Tsx

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

children

propertyReact.ReactNode

facetedFilters

propertyFacetedFilterConfig<T>

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

Example

Tsx

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

rowActions

propertyRowAction<ListQueryFields<T>>[]

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

property(data: any[]) => any[]

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

setTableOptions

property(table: TableOptions<any>) => TableOptions<any>

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

bulkActions

propertyBulkActionsInput

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

Tsx

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

registerRefresher

propertyPaginatedListRefresherRegisterFn

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

property(oldIndex: number, newIndex: number, item: any) => void | Promise<void>

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

disableDragAndDrop

propertyboolean

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.

ListPage

@vendure/dashboard Sourcev3.3.0

Auto-generates a list page with columns generated based on the provided query document fields.

Example

Tsx

import {    Button,    DashboardRouteDefinition,    ListPage,    PageActionBarRight,    DetailPageButton,} from '@vendure/dashboard';import { Link } from '@tanstack/react-router';import { PlusIcon } from 'lucide-react';// This function is generated for you by the `vendureDashboardPlugin` in your Vite config.// It uses gql-tada to generate TypeScript types which give you type safety as you write// your queries and mutations.import { graphql } from '@/gql';// The fields you select here will be automatically used to generate the appropriate columns in the// data table below.const getArticleList = graphql(`    query GetArticles($options: ArticleListOptions) {        articles(options: $options) {            items {                id                createdAt                updatedAt                isPublished                title                slug                body                customFields            }            totalItems        }    }`);const deleteArticleDocument = graphql(`    mutation DeleteArticle($id: ID!) {        deleteArticle(id: $id) {            result        }    }`);export const articleList: DashboardRouteDefinition = {    navMenuItem: {        sectionId: 'catalog',        id: 'articles',        url: '/articles',        title: 'CMS Articles',    },    path: '/articles',    loader: () => ({        breadcrumb: 'Articles',    }),    component: route => (        <ListPage            pageId="article-list"            title="Articles"            listQuery={getArticleList}            deleteMutation={deleteArticleDocument}            route={route}            customizeColumns={{                title: {                    cell: ({ row }) => {                        const post = row.original;                        return <DetailPageButton id={post.id} label={post.title} />;                    },                },            }}        >            <PageActionBarRight>                <Button render={<Link to="./new" />}>                    <PlusIcon className="mr-2 h-4 w-4" />                    New article                </Button>            </PageActionBarRight>        </ListPage>    ),};

Signature

function ListPage<T extends TypedDocumentNode<U, V>, U extends Record<string, any> = any, V extends ListQueryOptionsShape = ListQueryOptionsShape, AC extends AdditionalColumns<T> = AdditionalColumns<T>>(props: Readonly<ListPageProps<T, U, V, AC>>): void

Parameters

props

parameterReadonly<ListPageProps<T, U, V, AC>>

ListPageProps

@vendure/dashboard Sourcev3.3.0

Props to configure the ListPage component.

Signature

interface ListPageProps<T extends TypedDocumentNode<U, V>, U extends ListQueryShape, V extends ListQueryOptionsShape, AC extends AdditionalColumns<T>> {    pageId?: string;    route: AnyRoute | (() => AnyRoute);    title: string | React.ReactElement;    listQuery: T;    deleteMutation?: TypedDocumentNode<any, { id: string }>;    transformVariables?: (variables: V) => V;    onSearchTermChange?: (searchTerm: string) => NonNullable<V['options']>['filter'];    customizeColumns?: CustomizeColumnConfig<T>;    additionalColumns?: AC;    defaultColumnOrder?: (keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>)[];    defaultSort?: SortingState;    defaultVisibility?: Partial<        Record<keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>, boolean>    >;    children?: React.ReactNode;    facetedFilters?: FacetedFilterConfig<T>;    rowActions?: RowAction<ListQueryFields<T>>[];    transformData?: (data: any[]) => any[];    setTableOptions?: (table: TableOptions<any>) => TableOptions<any>;    bulkActions?: BulkActionsInput;    registerRefresher?: PaginatedListRefresherRegisterFn;    onReorder?: (oldIndex: number, newIndex: number, item: any) => void | Promise<void>;    disableDragAndDrop?: boolean;}

pageId

propertystring

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

propertyAnyRoute | (() => AnyRoute)

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

title

propertystring | React.ReactElement

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

listQuery

propertyT

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

Example

Tsx

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

propertyTypedDocumentNode<any, { id: string }>

transformVariables

property(variables: V) => V

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

Tsx

<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

property(searchTerm: string) => NonNullable<V['options']>['filter']

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.

Example

Tsx

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

customizeColumns

propertyCustomizeColumnConfig<T>

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

Example

Tsx

<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

propertyAC

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

Tsx

<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

property(keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>)[]

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

propertySortingState

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

Example

Tsx

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

defaultVisibility

propertyPartial< Record<keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>, boolean> >

Example

Tsx

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

children

propertyReact.ReactNode

facetedFilters

propertyFacetedFilterConfig<T>

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

Example

Tsx

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

rowActions

propertyRowAction<ListQueryFields<T>>[]

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

property(data: any[]) => any[]

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

setTableOptions

property(table: TableOptions<any>) => TableOptions<any>

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

bulkActions

propertyBulkActionsInput

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

Tsx

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

registerRefresher

propertyPaginatedListRefresherRegisterFn

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

property(oldIndex: number, newIndex: number, item: any) => void | Promise<void>

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

disableDragAndDrop

propertyboolean