PaginatedListDataTable | Vendure Docs

PaginatedList

Tsx

import { Money } from '@/vdb/components/data-display/money.js';import { PaginatedListDataTable } from '@/vdb/components/shared/paginated-list-data-table.js';import { Badge } from '@/vdb/components/ui/badge.js';import { Button } from '@/vdb/components/ui/button.js';import { Link } from '@tanstack/react-router';import { ColumnFiltersState, SortingState } from '@tanstack/react-table';import { useState } from 'react';import { customerOrderListDocument } from '../customers.graphql.js';interface CustomerOrderTableProps {    customerId: string;}export function CustomerOrderTable({ customerId }: Readonly<CustomerOrderTableProps>) {    const [page, setPage] = useState(1);    const [pageSize, setPageSize] = useState(10);    const [sorting, setSorting] = useState<SortingState>([{ id: 'orderPlacedAt', desc: true }]);    const [filters, setFilters] = useState<ColumnFiltersState>([]);    return (        <PaginatedListDataTable            listQuery={customerOrderListDocument}            transformVariables={variables => {                return {                    ...variables,                    customerId,                };            }}            defaultVisibility={{                id: false,                createdAt: false,                updatedAt: false,                type: false,                currencyCode: false,                total: false,            }}            customizeColumns={{                total: {                    header: 'Total',                    cell: ({ cell, row }) => {                        const value = cell.getValue();                        const currencyCode = row.original.currencyCode;                        return <Money value={value} currency={currencyCode} />;                    },                },                totalWithTax: {                    header: 'Total with Tax',                    cell: ({ cell, row }) => {                        const value = cell.getValue();                        const currencyCode = row.original.currencyCode;                        return <Money value={value} currency={currencyCode} />;                    },                },                state: {                    header: 'State',                    cell: ({ cell }) => {                        const value = cell.getValue() as string;                        return <Badge variant="outline">{value}</Badge>;                    },                },                code: {                    header: 'Code',                    cell: ({ cell, row }) => {                        const value = cell.getValue() as string;                        const id = row.original.id;                        return (                            <Button variant="ghost" render={<Link to={`/orders/${id}`} />}>                                {value}                            </Button>                        );                    },                },            }}            page={page}            itemsPerPage={pageSize}            sorting={sorting}            columnFilters={filters}            onPageChange={(_, page, perPage) => {                setPage(page);                setPageSize(perPage);            }}            onSortChange={(_, sorting) => {                setSorting(sorting);            }}            onFilterChange={(_, filters) => {                setFilters(filters);            }}        />    );}

Signature

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

Signature

interface PaginatedListDataTableProps<T extends TypedDocumentNode<U, V>, U extends ListQueryShape, V extends ListQueryOptionsShape, AC extends AdditionalColumns<T>> {    listQuery: T;    deleteMutation?: TypedDocumentNode<any, any>;    transformQueryKey?: (queryKey: any[]) => any[];    transformVariables?: (variables: V) => V;    customizeColumns?: CustomizeColumnConfig<T>;    additionalColumns?: AC;    defaultColumnOrder?: (keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>)[];    defaultVisibility?: Partial<Record<AllItemFieldKeys<T> | keyof AC, boolean>>;    onSearchTermChange?: (searchTerm: string) => NonNullable<V['options']>['filter'];    searchPlaceholder?: string;    page: number;    itemsPerPage: number;    sorting: SortingState;    columnFilters?: ColumnFiltersState;    onPageChange: (table: Table<any>, page: number, perPage: number) => void;    onSortChange: (table: Table<any>, sorting: SortingState) => void;    onFilterChange?: (table: Table<any>, filters: ColumnFiltersState) => void;    onColumnVisibilityChange?: (table: Table<any>, columnVisibility: VisibilityState) => void;    facetedFilters?: FacetedFilterConfig<T>;    rowActions?: RowAction<PaginatedListItemFields<T>>[];    bulkActions?: BulkActionsInput | false;    selectedItems?: PaginatedListItemFields<T>[];    onSelectionChange?: (selection: PaginatedListItemFields<T>[]) => void;    disableViewOptions?: boolean;    enableViews?: boolean;    transformData?: (data: PaginatedListItemFields<T>[]) => PaginatedListItemFields<T>[];    setTableOptions?: (table: TableOptions<any>) => TableOptions<any>;    registerRefresher?: PaginatedListRefresherRegisterFn;    onReorder?: (        oldIndex: number,        newIndex: number,        item: PaginatedListItemFields<T>,    ) => void | Promise<void>;    disableDragAndDrop?: boolean;    includeSelectionColumn?: boolean;    emptyStateAction?: React.ReactNode;    emptyStateIllustration?: React.ReactNode;    errorState?: (params: { error: Error; retry: () => void }) => React.ReactNode;    title?: React.ReactNode;    actions?: React.ReactNode;    frame?: 'card' | 'plain';}

listQuery

propertyT

deleteMutation

propertyTypedDocumentNode<any, any>

transformQueryKey

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

transformVariables

property(variables: V) => V

customizeColumns

propertyCustomizeColumnConfig<T>

additionalColumns

propertyAC

defaultColumnOrder

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

defaultVisibility

propertyPartial<Record<AllItemFieldKeys<T> | keyof AC, boolean>>

onSearchTermChange

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

Called whenever the debounced search term changes (including when it becomes empty). Return a partial filter to merge with the column / faceted filters. The returned filter is only applied when the term is non-empty — when the term is '', the returned value is discarded so that callers can write { field: { contains: searchTerm } } without producing tautological contains: '' clauses. The callback itself is still invoked on every change so pages can use it as a state-sync hook.

searchPlaceholder

propertystringv3.8.0

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

page

propertynumber

itemsPerPage

propertynumber

sorting

propertySortingState

columnFilters

propertyColumnFiltersState

onPageChange

property(table: Table<any>, page: number, perPage: number) => void

onSortChange

property(table: Table<any>, sorting: SortingState) => void

onFilterChange

property(table: Table<any>, filters: ColumnFiltersState) => void

Called when the user changes the column filters. When omitted, the table is treated as read-only with respect to filtering: the saved-views tabs and the "Add filter" menu are not rendered. Useful for embedded tables (e.g. dashboard widgets) that apply preset filters via transformVariables.

onColumnVisibilityChange

property(table: Table<any>, columnVisibility: VisibilityState) => void

facetedFilters

propertyFacetedFilterConfig<T>

rowActions

propertyRowAction<PaginatedListItemFields<T>>[]

bulkActions

propertyBulkActionsInput | false

selectedItems

propertyPaginatedListItemFields<T>[]

onSelectionChange

property(selection: PaginatedListItemFields<T>[]) => void

disableViewOptions

propertyboolean

enableViews

propertybooleanv3.8.0

Default:false

Enables saved-view controls for this table. This should be used for tables which represent a whole data set, such as top-level list pages. It should not be enabled for embedded tables or tables whose query is already scoped by a predefined filter.

transformData

property(data: PaginatedListItemFields<T>[]) => PaginatedListItemFields<T>[]

setTableOptions

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

registerRefresher

propertyPaginatedListRefresherRegisterFn

onReorder

property

(         oldIndex: number,         newIndex: number,         item: PaginatedListItemFields<T>,     ) => void | Promise<void>

Callback when items are reordered via drag and drop. 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

includeSelectionColumn

propertyboolean

Default:true

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

emptyStateAction

propertyReact.ReactNode

An optional action rendered inside the first-run empty state (i.e. when the list has no items and no active filters/search). Typically a "create your first X" CTA. The page owns this because the table cannot know the create route or the permissions that gate it.

emptyStateIllustration

propertyReact.ReactNode

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.

errorState

property(params: { error: Error; retry: () => void }) => React.ReactNode

Render prop invoked when the underlying list query fails. Receives the error and a retry callback (re-runs the query) and should return the content to display in place of the table — typically an ErrorState. When omitted, a failed query renders as an empty table.

title

propertyReact.ReactNodev3.8.0

An optional title rendered in the table's header band. Intended for tables embedded in detail pages (e.g. "Product variants").

actions

propertyReact.ReactNodev3.8.0

Optional action buttons (e.g. a "Manage variants" CTA) rendered in the table's header band, next to the view-options and refresh controls.

frame

property'card' | 'plain'v3.8.0

Default:'card'

The table's frame. 'card' (default) renders the table on its own card; 'plain' renders the same band structure without the card chrome, for a table embedded in an existing card (e.g. a dashboard widget).