## Usage

The `<Pagination />` component is used to split up a large data set into several pages. It allows users to navigate these pages and set how many items they want to view per page.

```tsx live
const [currentPage, setCurrentPage] = useState(1);
const [currentItemsPerPage, setCurrentItemsPerPage] = useState(10);

const onPageUpdate = (
  paginationState: PaginationState,
  prevPaginationState: PaginationState,
  paginationDiff: Partial<PaginationState>
) => {
  // See the pagination state update in the console
  console.info(paginationState, prevPaginationState, paginationDiff);

  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage(currentPage);
  setCurrentItemsPerPage(currentItemsPerPage);
};

return (
  <Pagination
    currentPage={currentPage}
    currentItemsPerPage={currentItemsPerPage}
    itemsCount={100}
    onPageUpdate={onPageUpdate}
  />
);
```

## Concept

The `Pagination` component is designed to be used as a controlled component, that notifies you of valid page changes with the `onPageUpdate` callback.

This saves you from having to implement:

- Handlers for all four buttons.
- Handlers for the items per page select-list.
- Calculating the page changes when the user changes the items per page.
- Keeping the user on the page with the same data when they change items per page.
- Ensuring a valid page is always displayed.

Use the two inputs below to mimic your `currentPage` and `currentItemsPerPage` from your parent component's state. Notice how setting an invalid currentPage (e.g. 1000) still displays a valid page in the Pagination component.

```tsx live
const [currentPage, setCurrentPage] = useState(1);
const [currentItemsPerPage, setCurrentItemsPerPage] = useState(10);

const onPageUpdate = (
  paginationState: PaginationState,
  prevPaginationState: PaginationState,
  paginationDiff: Partial<PaginationState>
) => {
  // See the pagination state update in the console
  console.info(paginationState, prevPaginationState, paginationDiff);

  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage(currentPage);
  setCurrentItemsPerPage(currentItemsPerPage);
};

const onSubmitCurrentPageOverride = (event: React.FormEvent<HTMLFormElement>) => {
  event.preventDefault();
  setCurrentPage(Number((event.currentTarget.elements.namedItem('currentPageOverride') as HTMLInputElement).value));
};

const onSubmitCurrentItemsPerPageOverride = (event: React.FormEvent<HTMLFormElement>) => {
  event.preventDefault();
  setCurrentItemsPerPage(
    Number((event.currentTarget.elements.namedItem('currentItemsPerPageOverride') as HTMLInputElement).value)
  );
};

return (
  <Grid gridTemplateColumns="1fr 1fr" gap="xxlarge">
    <form onSubmit={onSubmitCurrentPageOverride}>
      <Field label="currentPage">
        <TextInput name="currentPageOverride" type="number" />
      </Field>

      <Button type="submit" label="Set current page" />
    </form>

    <form onSubmit={onSubmitCurrentItemsPerPageOverride}>
      <Field label="currentItemsPerPage">
        <SelectInput
          onChange={(event) => console.info(event)}
          name="currentItemsPerPageOverride"
          items={[
            { label: 10, value: 10 },
            { label: 20, value: 20 },
            { label: 30, value: 30 },
            { label: 40, value: 40 },
            { label: 50, value: 50 },
            { label: 100, value: 100 },
          ]}
        />
      </Field>

      <Button type="submit" label="Set current items per page" />
    </form>

    <Box gridColumn="1 / -1">
      <Pagination
        currentPage={currentPage}
        currentItemsPerPage={currentItemsPerPage}
        itemsCount={100}
        onPageUpdate={onPageUpdate}
      />
    </Box>
  </Grid>
);
```

## Integrating Pagination in your app

There are two key parts to integrating the Pagination component and accessing its state: the first part is [pagination state](#pagination-state) which is available to the parent by passing a function to the second part, [onPageUpdate](#onpageupdate).

### Pagination state

The pagination state object is the first parameter of the `onPageUpdate` callback and takes the following shape:

```tsx
type PaginationState = {
  currentPage: number;
  currentItemsPerPage: ItemsPerPageOption; // a number in the `itemsPerPageOptions` array
  prevPage: number | null;
  nextPage: number | null;
  rangeStart: number;
  rangeEnd: number;
};
```

### onPageUpdate

By passing in a callback for `onPageUpdate` you can access the current state of the `Pagination` component and react accordingly. e.g. when a new `currentPage` value is set you can fetch the new data or pre-fetch data for the `prevPage` and `nextPage`, if that's desirable. `onPageUpdate` will run everytime the user changes the state of the Pagination component or when `currentPage` or `currentItemsPerPage` props are updated. Most importantly, it will always give you valid values for these two props.

<Notice tone="caution" title="Always use onPageUpdate for accurate values">
  <Text>
    The Pagination component runs a series of validity checks on page updates, so it's extremely important to use the
    first parameter of onPageUpdate to ensure you have a valid currentPage and currentItemsPerPage.
  </Text>
</Notice>

Watch "Current pagination state" change as you interact with the component below, e.g. press "Next page" or change the "Items per page".

```tsx live
const [currentPage, setCurrentPage] = useState(1);
const [currentItemsPerPage, setCurrentItemsPerPage] = useState(10);

const [displayState, setDisplayState] = useState<PaginationState>({
  currentPage: 1,
  currentItemsPerPage: 10,
  prevPage: null,
  nextPage: 2,
  rangeStart: 1,
  rangeEnd: 100,
});

const {
  currentPage: currentPageDisplay,
  currentItemsPerPage: currentItemsPerPageDisplay,
  prevPage,
  nextPage,
  rangeStart,
  rangeEnd,
} = displayState;

const onPageUpdate = (paginationState: PaginationState) => {
  // Use the `paginationState` to update data on your page, e.g. fetch data for `paginationState.currentPage` and display it in a table
  setDisplayState(paginationState);

  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage(currentPage);
  setCurrentItemsPerPage(currentItemsPerPage);
};

return (
  <Flex gap="small" flexDirection="column">
    <Heading level={4}>Current pagination state:</Heading>

    <Grid gridTemplateColumns="max-content 1fr" columnGap="xsmall" rowGap="xxsmall">
      <Text fontFamily="mono" className={css({ textAlign: 'right' })}>
        currentPage:{' '}
      </Text>
      <Text fontFamily="mono" fontWeight="bold">
        {currentPageDisplay}
      </Text>
      <Text fontFamily="mono" className={css({ textAlign: 'right' })}>
        currentItemsPerPage:{' '}
      </Text>
      <Text fontFamily="mono" fontWeight="bold">
        {currentItemsPerPageDisplay}
      </Text>
      <Text fontFamily="mono" className={css({ textAlign: 'right' })}>
        prevPage:{' '}
      </Text>
      <Text fontFamily="mono" fontWeight="bold">
        {prevPage === null ? 'null' : prevPage}
      </Text>
      <Text fontFamily="mono" className={css({ textAlign: 'right' })}>
        nextPage:{' '}
      </Text>
      <Text fontFamily="mono" fontWeight="bold">
        {nextPage === null ? 'null' : nextPage}
      </Text>
      <Text fontFamily="mono" className={css({ textAlign: 'right' })}>
        rangeStart:{' '}
      </Text>
      <Text fontFamily="mono" fontWeight="bold">
        {rangeStart}
      </Text>
      <Text fontFamily="mono" className={css({ textAlign: 'right' })}>
        rangeEnd:{' '}
      </Text>
      <Text fontFamily="mono" fontWeight="bold">
        {rangeEnd}
      </Text>
    </Grid>

    <Pagination
      currentPage={currentPage}
      currentItemsPerPage={currentItemsPerPage}
      itemsCount={100}
      onPageUpdate={onPageUpdate}
    />
  </Flex>
);
```

<Notice>
  <Text>
    The second and third parameters for the onPageUpdate function offer the previous pagination state and a diff,
    respectively.
  </Text>
</Notice>

A TypeScript example of the `onPageUpdate` function used to fetch data and update local state could be:

```tsx
const [currentPage, setCurrentPage] = useState(1);
const [currentItemsPerPage, setCurrentItemsPerPage] = useState(10);
const [tableData, setTableData] = useState({});

useEffect(() => {
  // Define yor API search parameters with valid data from the Pagination component
  const searchParams = new URLSearchParams({
    page: `${currentPage}`,
    itemsPerPage: `${currentItemsPerPage}`,
  });

  // Perform the API request using the above search parameters
  fetch(`/my-api?${searchParams}`)
    .then((res) => res.json())
    .then(setTableData);
}, [currentPage, currentItemsPerPage]);

const onPageUpdate = (
  paginationState: PaginationState,
  prevPaginationState: PaginationState,
  paginationStateDiff: Partial<PaginationState>
) => {
  // Take a look in the console to see each of these values update
  console.info({ paginationState, prevPaginationState, paginationStateDiff });

  const { currentPage, currentItemsPerPage } = paginationState;
  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  setCurrentPage(currentPage);
  setCurrentItemsPerPage(currentItemsPerPage);
};

return (
  <Pagination
    currentPage={currentPage}
    currentItemsPerPage={currentItemsPerPage}
    itemsCount={100}
    onPageUpdate={onPageUpdate}
  />
);
```

## Items per page

The user may select, from a menu, the number of items they wish to be displayed per page. The default options are `10`, `20`, `30`, `40`, `50`, and `100`. The default values can be set by passing a value to the `useState` function for each of `currentPage` and `currentItemsPerPage`. If an invalid value is defined, the Pagination component will find a valid value and return it via the `onPageUpdate` function.

```tsx live
const [currentPage, setCurrentPage] = useState(4);
const [currentItemsPerPage, setCurrentItemsPerPage] = useState(60);

const onPageUpdate = (paginationState: PaginationState) => {
  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage(currentPage);
  setCurrentItemsPerPage(currentItemsPerPage);
};

return (
  <Pagination
    currentPage={currentPage}
    currentItemsPerPage={currentItemsPerPage}
    itemsPerPageOptions={[15, 30, 60, 120]}
    itemsCount={600}
    onPageUpdate={onPageUpdate}
  />
);
```

## Navigation

There are four buttons for navigation, displayed from left to right with the following `aria-label`s:

- `First page`
- `Previous page`
- `Next page`
- `Last page`

### Display logic

When a user is on:

- The first page: the `First page` and `Previous page` buttons will be disabled.
- The last page: the `Next page` and `Last page` buttons will be disabled.

When the smallest number of items to display is equal to or less than the smallest option for items per page, then:

- The controls will be hidden.
- The pagination content will be centred.

```tsx live
const [currentPage1, setCurrentPage1] = useState(1);
const [currentItemsPerPage1, setCurrentItemsPerPage1] = useState(10);
const [currentPage2, setCurrentPage2] = useState(10);
const [currentItemsPerPage2, setCurrentItemsPerPage2] = useState(10);
const [currentPage3, setCurrentPage3] = useState(1);
const [currentItemsPerPage3, setCurrentItemsPerPage3] = useState(10);
const [currentPage4, setCurrentPage4] = useState(1);
const [currentItemsPerPage4, setCurrentItemsPerPage4] = useState(10);

const onPageUpdate1 = (paginationState: PaginationState) => {
  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage1(currentPage);
  setCurrentItemsPerPage1(currentItemsPerPage);
};
const onPageUpdate2 = (paginationState: PaginationState) => {
  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage2(currentPage);
  setCurrentItemsPerPage2(currentItemsPerPage);
};
const onPageUpdate3 = (paginationState: PaginationState) => {
  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage3(currentPage);
  setCurrentItemsPerPage3(currentItemsPerPage);
};
const onPageUpdate4 = (paginationState: PaginationState) => {
  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage4(currentPage);
  setCurrentItemsPerPage4(currentItemsPerPage);
};

return (
  <Flex flexDirection="column" gap="xxlarge">
    <Flex flexDirection="column" gap="small">
      <Heading as="h4" level={6}>
        First page (First page and Previous page buttons disabled)
      </Heading>
      <Pagination
        currentPage={currentPage1}
        currentItemsPerPage={currentItemsPerPage1}
        itemsCount={100}
        onPageUpdate={onPageUpdate1}
      />
    </Flex>

    <Flex flexDirection="column" gap="small">
      <Heading as="h4" level={6}>
        Last page (Last page and Next page buttons disabled)
      </Heading>
      <Pagination
        currentPage={currentPage2}
        currentItemsPerPage={currentItemsPerPage2}
        itemsCount={100}
        onPageUpdate={onPageUpdate2}
      />
    </Flex>

    <Flex flexDirection="column" gap="small">
      <Heading as="h4" level={6}>
        One page of items (the label is centred and navigation buttons disabled)
      </Heading>
      <Pagination
        currentPage={currentPage3}
        currentItemsPerPage={currentItemsPerPage3}
        itemsCount={10}
        onPageUpdate={onPageUpdate3}
      />
    </Flex>

    <Flex flexDirection="column" gap="small">
      <Heading as="h4" level={6}>
        No items to display (the label is centred and navigation buttons disabled)
      </Heading>
      <Pagination
        currentPage={currentPage4}
        currentItemsPerPage={currentItemsPerPage4}
        itemsCount={0}
        onPageUpdate={onPageUpdate4}
      />
    </Flex>
  </Flex>
);
```

## Items label

By default, elements in the list (e.g. rows in a table) are referred to with the term "Items", and used in "Items per page" and "1 - 10 of 100 items". This can be customised by setting values for both `itemsLabelPlural` and `itemsLabelSingular`. The singular version is used when there is only one item to show.

```tsx live
const [currentPage1, setCurrentPage1] = useState(1);
const [currentItemsPerPage1, setCurrentItemsPerPage1] = useState(10);
const [currentPage2, setCurrentPage2] = useState(1);
const [currentItemsPerPage2, setCurrentItemsPerPage2] = useState(10);

const onPageUpdate1 = (paginationState: PaginationState) => {
  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage1(currentPage);
  setCurrentItemsPerPage1(currentItemsPerPage);
};
const onPageUpdate2 = (paginationState: PaginationState) => {
  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage2(currentPage);
  setCurrentItemsPerPage2(currentItemsPerPage);
};

return (
  <Flex flexDirection="column" gap="xxlarge">
    <Flex flexDirection="column" gap="small">
      <Heading as="h4" level={6}>
        Custom items label plural
      </Heading>
      <Pagination
        currentPage={currentPage1}
        currentItemsPerPage={currentItemsPerPage1}
        itemsLabelPlural="companies"
        itemsLabelSingular="company"
        itemsCount={100}
        onPageUpdate={onPageUpdate1}
      />
    </Flex>

    <Flex flexDirection="column" gap="small">
      <Heading as="h4" level={6}>
        Custom items label singular
      </Heading>
      <Pagination
        currentPage={currentPage2}
        currentItemsPerPage={currentItemsPerPage2}
        itemsLabelPlural="companies"
        itemsLabelSingular="company"
        itemsCount={1}
        onPageUpdate={onPageUpdate2}
      />
    </Flex>
  </Flex>
);
```

## Size

There are two pagination sizes, small and medium (default). The spacing will change depending on the size selected.

```tsx live
const [currentPage, setCurrentPage] = useState(1);
const [currentItemsPerPage, setCurrentItemsPerPage] = useState(5);

const onPageUpdate = (paginationState: PaginationState) => {
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage(currentPage);
  setCurrentItemsPerPage(currentItemsPerPage);
};
return (
  <Flex flexDirection="column" gap="large">
    <Heading as="h4" level={6}>
      Medium (default)
    </Heading>
    <Pagination
      size="medium"
      currentPage={currentPage}
      currentItemsPerPage={currentItemsPerPage}
      itemsCount={100}
      onPageUpdate={onPageUpdate}
    />
    <Heading as="h4" level={6}>
      Small
    </Heading>
    <Pagination
      size="small"
      currentPage={currentPage}
      currentItemsPerPage={currentItemsPerPage}
      itemsCount={100}
      onPageUpdate={onPageUpdate}
    />
  </Flex>
);
```

## Block

Use the block prop to make the pagination fill its container's width.

**Note:** The block prop splits the items per page elements from navigation elements to opposite sides of the container.

```tsx live
const [currentPage, setCurrentPage] = useState(1);
const [currentItemsPerPage, setCurrentItemsPerPage] = useState(5);

const onPageUpdate = (paginationState: PaginationState) => {
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage(currentPage);
  setCurrentItemsPerPage(currentItemsPerPage);
};
return (
  <Flex flexDirection="column" gap="large">
    <Pagination
      block
      currentPage={currentPage}
      currentItemsPerPage={currentItemsPerPage}
      itemsCount={100}
      onPageUpdate={onPageUpdate}
    />
  </Flex>
);
```

## Items per page

If the option of items per page is set to a single number, the select will be hidden from view.

```tsx live
const [currentPage, setCurrentPage] = useState(1);
const [currentItemsPerPage, setCurrentItemsPerPage] = useState(5);

const onPageUpdate = (paginationState: PaginationState) => {
  const { currentPage, currentItemsPerPage } = paginationState;
  setCurrentPage(currentPage);
  setCurrentItemsPerPage(currentItemsPerPage);
};
return (
  <Flex flexDirection="column" gap="large">
    <Pagination
      currentPage={currentPage}
      currentItemsPerPage={currentItemsPerPage}
      itemsPerPageOptions={[5]}
      itemsCount={100}
      onPageUpdate={onPageUpdate}
    />
  </Flex>
);
```

A control for navigating to the next or previous page of a large data set.

Pagination

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources

The value of the selected items per page SelectInput.

currentItemsPerPage

currentPage

itemsCount

Callback to run when pagination state is updated, e.g. on navigation to a new page or when "Items per page" value is updated. You can use the `paginationState` parameter to perform additional tasks, e.g. data fetching.

onPageUpdate

What to call `Items`, e.g. used in "Items per page". Defaults to `Items`.

itemsLabelPlural

What to call `Item`, e.g. used in "1 of 1 item". Defaults to `Item`.

itemsLabelSingular

The page to initially display. Defaults to the value of the `indexBased` prop, which is the first page.

initialPage

The number of items per page to initially load. Defaults to first in `itemsPerPageOptions` list.

initialItemsPerPage

The index based system to use. Defaults to `1`. E.g. a value of `0` means the first page will be `0` and a value of `1` means the first page will be `1`.

indexBased

A list of items per page to populate the menu with. Defaults to `[10, 20, 30, 40, 50, 100]`.

itemsPerPageOptions

Controls the size of elements within the pagination component. Defaults to `medium

size

If set to true the pagination component will fill the width of the parent and visually separate items per page and navigation elements. Defaults to `false`

block

Prop	Required	Description	Type
`currentItemsPerPage`	✅	The value of the selected items per page SelectInput.	number
`currentPage`	✅	The current page of the range.	number
`itemsCount`	✅	Total number of items.	number
`onPageUpdate`	✅	Callback to run when pagination state is updated, e.g. on navigation to a new page or when "Items per page" value is updated. You can use the paginationState parameter to perform additional tasks, e.g. data fetching.	(paginationState: PaginationState, prevPaginationState: PaginationState, paginationStateDiff: Partial<PaginationState>) => void
`itemsLabelPlural`	—	What to call Items, e.g. used in "Items per page". Defaults to Items.	string
`itemsLabelSingular`	—	What to call Item, e.g. used in "1 of 1 item". Defaults to Item.	string
`initialPage`	—	The page to initially display. Defaults to the value of the indexBased prop, which is the first page.	number
`initialItemsPerPage`	—	The number of items per page to initially load. Defaults to first in itemsPerPageOptions list.	number
`indexBased`	—	The index based system to use. Defaults to 1. E.g. a value of 0 means the first page will be 0 and a value of 1 means the first page will be 1.	0 \| 1
`itemsPerPageOptions`	—	A list of items per page to populate the menu with. Defaults to [10, 20, 30, 40, 50, 100].	[number, ...number[]]
`size`	—	Controls the size of elements within the pagination component. Defaults to medium	"small" \| "medium"
`block`	—	If set to true the pagination component will fill the width of the parent and visually separate items per page and navigation elements. Defaults to false	boolean