import { DataTable } from '@uhg-abyss/web/ui/DataTable';
import { useDataTable } from '@uhg-abyss/web/hooks/useDataTable';

Client-side pagination

The DataTable.Pagination sub-component utilizes the Pagination component to allow users to see a data set in a more manageable way.

<DataTable.Pagination />

The simplest way to paginate data with the DataTable is to use client-side pagination. This means that the entire data set is loaded into the browser, and the DataTable handles the pagination on the client side.

Info

For information about server-side pagination, see our Server-side pagination docs.

To enable client-side pagination, set paginationConfig.enablePagination to true.

const dataTableProps = useDataTable({
  // ...
  paginationConfig: {
    enablePagination: true,
  },
  // ...
});

The two parameters used to configure the pagination state are pageIndex and pageSize. pageIndex is the zero-based index of the current page, and pageSize is the number of rows to display per page. By default, the pageIndex is 0 and the pageSize is 10.

To manage the pagination state, provide a function to the tableConfig.onPaginationChange property and set the state.pagination property; we recommend using useState for this, as shown below.

const [pagination, setPagination] = useState({
  pageIndex: 0,
  pageSize: 10,
});

const dataTableProps = useDataTable({
  // ...
  tableConfig: {
    state: {
      pagination,
    },
    onPaginationChange: setPagination,
  },
  // ...
});

Extended variant

By default, the DataTable.Pagination sub-component uses the 'extended' variant of the Pagination component.

<DataTable.Pagination variant="extended" />

Minimal variant

The 'minimal' variant is a more compact pagination version.

<DataTable.Pagination variant="minimal" />

Page size dropdown

By default, the page size dropdown is hidden. To show the page size dropdown, set showPageSizeDropdown in the DataTable.Pagination component to true.

<DataTable.Pagination showPageSizeDropdown={true} />

When enabled, the page size dropdown will display three options: 10, 15, and 20. You can customize the page size options by passing an array of numbers to the paginationConfig.pageSizeOptions property.

const dataTableProps = useDataTable({
  // ...
  paginationConfig: {
    pageSizeOptions: [10, 20, 30, 40, 50],
  },
  // ...
});

To control how many options are visible before a scrollbar appears, use the paginationConfig.maxListHeight property. Increasing this value allows all options to be visible without scrolling.

const dataTableProps = useDataTable({
  // ...
  paginationConfig: {
    pageSizeOptions: [10, 20, 30, 40, 50],
    maxListHeight: '250px',
  },
  // ...
});

Label

For accessibility purposes, it is important to provide a descriptive label for the pagination component, especially if there are multiple such components on the page, whether in a DataTable or not. This label will be used by screen readers to announce the purpose of the pagination controls.

By default, the table will add a label of ${title} pagination if there is only one pagination instance in the table. If there are two, it will add labels of ${title} primary pagination and ${title} secondary pagination for the first and second instances, respectively.

Warning

We don't recommend using more than two pagination instances per table, but if you do, all instances besides the first will have the label ${title} secondary pagination by default. In this case, you must provide explicit label props to distinguish each pagination instance.

Note

DataTable.Pagination is still detected even if you wrap it in your own custom component, but the first instance to render can't know a sibling exists until that sibling actually renders and registers itself. If it's wrapped, DataTable can't find it ahead of time by scanning its own children. In that case, the first instance falls back to the single-instance wording (${title} pagination) rather than ${title} primary pagination, while later instances still correctly detect the others and use ${title} secondary pagination. Pass an explicit label prop if you need the first instance labeled consistently with the rest.

Programmatic pagination

Since the pagination state is managed externally, it is easy to programmatically change the page index. This can be useful for implementing custom pagination controls or for navigating to a specific page based on user input.

Component Tokens

Tip

Click on the token row to copy the token to your clipboard.

DataTable Tokens

Search tokens

Token Name	Value
data-table.color.border.column-header.drag	#002677
data-table.color.border.root	#CBCCCD
data-table.color.border.row.drag	#002677
data-table.color.border.table	#CBCCCD
data-table.color.icon.column-header-menus.grouping.active	#002677
data-table.color.icon.column-header-menus.grouping.hover	#004BA0
data-table.color.icon.column-header-menus.grouping.rest	#196ECF
data-table.color.icon.column-header-menus.sorting.active	#002677
data-table.color.icon.column-header-menus.sorting.hover	#004BA0
data-table.color.icon.column-header-menus.sorting.rest	#196ECF
data-table.color.icon.drag-handle.active	#002677
data-table.color.icon.drag-handle.hover	#004BA0
data-table.color.icon.drag-handle.rest	#196ECF
data-table.color.icon.expander.active	#002677
data-table.color.icon.expander.disabled	#7D7F81
data-table.color.icon.expander.hover	#004BA0
data-table.color.icon.expander.rest	#196ECF
data-table.color.icon.utility.drag-alternative.active	#000000
data-table.color.icon.utility.drag-alternative.disabled	#7D7F81
data-table.color.icon.utility.drag-alternative.hover	#323334
data-table.color.icon.utility.drag-alternative.rest	#4B4D4F
data-table.color.icon.utility.filter.active	#002677
data-table.color.icon.utility.filter.hover	#004BA0
data-table.color.icon.utility.filter.rest	#196ECF
data-table.color.surface.column-header.active	#E5F8FB
data-table.color.surface.column-header.default	#F3F3F3
data-table.color.surface.column-header.drag	#E5F8FB
data-table.color.surface.footer	#F3F3F3
data-table.color.surface.header	#FFFFFF
data-table.color.surface.root	#FFFFFF
data-table.color.surface.row.drag	#E5F8FB
data-table.color.surface.row.even	#FAFCFF
data-table.color.surface.row.highlighted	#E5F8FB
data-table.color.surface.row.hover	#F3F3F3
data-table.color.surface.row.odd	#FFFFFF
data-table.color.surface.table	#FFFFFF
data-table.color.text.cell	#4B4D4F
data-table.color.text.column-header	#4B4D4F
data-table.color.text.header.heading	#002677
data-table.color.text.header.paragraph	#4B4D4F
data-table.border-radius.all.container	8px
data-table.border-width.all.column-header.drag	2px
data-table.border-width.all.root	1px
data-table.border-width.all.row.drag	2px
data-table.border-width.all.table	1px
data-table.sizing.all.icon.column-header-menus	20px
data-table.sizing.all.icon.drag-handle-row	24px
data-table.sizing.all.icon.expander-column	24px
data-table.sizing.all.icon.utility.drag-alternative	20px
data-table.sizing.all.icon.utility.filter	20px
data-table.sizing.height.cell.comfortable	48px
data-table.sizing.height.cell.compact	32px
data-table.sizing.height.cell.cozy	40px
data-table.spacing.gap.horizontal.button-group	8px
data-table.spacing.gap.horizontal.cell	4px
data-table.spacing.gap.horizontal.drag-alternative	8px
data-table.spacing.gap.horizontal.input-container	8px
data-table.spacing.gap.horizontal.slot-wrapper	24px
data-table.spacing.gap.vertical.column-header	2px
data-table.spacing.gap.vertical.header	4px
data-table.spacing.gap.filter-two-inputs	16px
data-table.spacing.padding.all.column-header	8px
data-table.spacing.padding.all.column-header-menus	2px
data-table.spacing.padding.all.header	16px
data-table.spacing.padding.all.result-text	16px
data-table.spacing.padding.all.slot-wrapper	16px
data-table.spacing.padding.horizontal.cell	8px
data-table.spacing.padding.vertical.button-group	8px
data-table.spacing.padding.vertical.cell	4px
data-table.elevation.column.pinned.left	6px 0px 8px -2px rgba(0,0,0,0.16)
data-table.elevation.column.pinned.right	-6px 0px 8px -2px rgba(0,0,0,0.16)
data-table.elevation.column-header	0px 6px 8px -2px rgba(0,0,0,0.16)
data-table.elevation.table-settings-dropdown.section-header	0px 2px 4px -2px rgba(0,0,0,0.16)