--- title: "Pagination" slug: pagination category: component type: documentation version: 20.0.0 tokens: 4207 source: https://ovh.github.io/design-system/v20.0.0/llms/react-components-pagination--documentation.txt --- # Pagination _A **Pagination** component splits a long list into numbered pages and lets users move between them, whether a page is a portion of the current view or a destination with a URL of its own._ ## Overview The **Pagination** component divides a list into discrete pages and provides the controls to move between them, keeping a large set of items browsable without overwhelming the interface. A page can be a portion of the current view, swapped in place without leaving the page, or a page of its own. **Pagination** can include various controls like next/previous controls, page numbers, an items per page selector and a go-to-page input. | | | |---|---| | Name | Pagination | | Also known as | Page navigation | | Design | https://www.figma.com/design/9jDDTcR4a9jPRFcdjawAlf/ODS---UI-Kit?node-id=47-7743 | | Source | https://github.com/ovh/design-system/tree/master/packages/ods-react/src/components/pagination | ## Usage A **Pagination** component is used in two situations, and each one calls for a different kind of control : * To navigate among a [Table](https://ovh.github.io/design-system/v20.0.0/components/table) component, or any content swapped inside the page the user is already on. * To browse a set of items spread over pages of their own, each with a URL (products list, public catalogue, documentation index, ...), see "Pages as links" below. ### Dos & Don'ts **Do** - Use Pagination when users need to move through a long list in a structured and orderly way - Ensure Pagination is used when the total number of pages is known or predictable - Display a reasonable number of items per page (typically around 20 to 30) to balance readability and navigation - Use Next/Previous controls and page numbers to help users track their position in the list - Turn the pages into links when each page has its own URL, so that they can be crawled, opened in a new tab and restored on reload **Don't** - Don't use Pagination when the total content fits into a single page - Avoid Pagination if the number of pages is unpredictable or constantly changing. In those cases, consider infinite scrolling or "Load more" patterns instead - Don't make Pagination the only method of navigation if users might need to filter or search within the dataset - Don't render a page that navigates as a Button, nor a page that only swaps content as a link: the role is what assistive technologies announce ### Best Practices in Context 1. **Pagination** 2. **Total items per page select** 3. **Total amount of items** 4. **Previous/Next buttons** 5. **Ellipsis** 6. **Current page button** 7. **Unselected page button** The anatomy above describes the default **Pagination**, whose pages are [Buttons](https://ovh.github.io/design-system/v20.0.0/components/button). When the pages are links, the same anatomy is rendered with the [Link](https://ovh.github.io/design-system/v20.0.0/components/link) style instead, as described in "Pages as links" below. ## Placement **Pagination** is presented to the user near the container it uses for pagination; it can be located just above or below it. Usually, the **Pagination** is end-aligned horizontally, as its usage is not principal to the container. ## Behavior ### Amount of items per page The number of items displayed in **Pagination** is depending on its referential. However, there are few rules to be applied to display it correctly. Number of items in the component can be chunked in packs of : - 10 - 25 - 50 - 100 - 300 This value is conditioning the number of items that will be displayed per page. By default, 10 items per page are displayed, but it can be set to match your need. ### Amount of pages A maximum of 6 numbered pages can be visible at once, with a minimum of 1. The previous and next controls are always visible, no matter what the amount of pages. Depending on the current page number and the amount of pages, here are the different displays of the whole component: - If amount of pages is less than 7, all numbered pages can be visible at once - If amount of pages is 7 or more : - If current page is the 4th one or less, the first 5 numbered pages are present, then an ellipsis and the last numbered page corresponding of the amount of pages - If current page is the 4th to last or more, the first page is displayed followed by an ellipsis and the last 5 numbered pages - If current page is between the previous bounds, the following are displayed, in order : - the first page, - an ellipsis, - 3 numbered pages, corresponding to : previous-to-current / current / next-to-current page, - an ellipsis, - the last numbered page Those counts hold whatever the pages are made of: they are rendered as [Buttons](https://ovh.github.io/design-system/v20.0.0/components/button) or as [Links](https://ovh.github.io/design-system/v20.0.0/components/link) depending on what activating one does, as described in "Pages as links" below. ### Go to page Allows users to directly select a page from an number input. ### Pages as links Where the **Pagination** is used to move between actual pages, each with a URL of its own, the pages must be links rather than Buttons. By default a page is a [Button](https://ovh.github.io/design-system/v20.0.0/components/button): activating it swaps the content in place, and nothing outside the component knows about it. That fits for example a paginated [Table](https://ovh.github.io/design-system/v20.0.0/components/table). As soon as a page is a destination, provide `getPageUrl` and the pages become real links. Because those pages navigate, they are rendered with the [Link](https://ovh.github.io/design-system/v20.0.0/components/link) style rather than the [Button](https://ovh.github.io/design-system/v20.0.0/components/button) style: a button looks like a button, a link looks like a link. What changes in link mode: - Every page the user can go to is a [Link](https://ovh.github.io/design-system/v20.0.0/components/link) carrying an `href` - The active page leads nowhere: it carries no `href` and stays out of the tab order. It reads as emphasised text and is exposed as a disabled link carrying [aria-current="page"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current) - With `disabled`, every link keeps its `href`, as a disabled [Link](https://ovh.github.io/design-system/v20.0.0/components/link) does: activating it does nothing, but crawlers still see the destination and a middle click still opens it #### Wiring link mode In link mode the URL holds the state of the **Pagination**, the active page and the number of items per page alike. Following a link changes the URL, and the component renders whatever the URL says: read both back from it and pass them as `page` and `pageSize`. ```tsx { const [searchParams] = useSearchParams(); const totalItems = 500; // The URL can hold anything: a size that is not a positive integer falls back on 10, and the // page is kept within the listing. const size = Number(searchParams.get('size')); const pageSize = Number.isSafeInteger(size) && size > 0 ? size : 10; const requestedPage = Number(searchParams.get('page')); const page = Number.isInteger(requestedPage) ? Math.min(Math.max(requestedPage, 1), Math.ceil(totalItems / pageSize)) : 1; // Merged into the current query, so that a sort or a filter it holds survives the navigation. function getPageUrl({ page, pageSize }: PaginationPageUrlDetail) { const params = new URLSearchParams(searchParams); params.set('page', String(page)); params.set('size', String(pageSize)); return `?${params}`; } return ( ); } ``` Three consequences follow from the URL being in charge: - **`onPageChange` does not fire when a link is followed.** The browser already did the work, and the new page is in the URL. It still fires for the controls that are not links, which have no href to follow: navigate to the matching URL from there. The same goes for `onPageSizeChange`. - **Never derive `page` from a callback during a click.** There is nothing to derive it from any more, which is the point: were the component to move mid-click, it would rewrite the previous / next href before the browser followed it, and the user would land one page further than the link they clicked. - **Validate what you read from the URL.** A URL can hold anything, and the component renders what it is given. On a listing of 20 pages, `?page=99` leaves the bar without an active page and its "Previous" link pointing to page 98, then 97, down to 21: a trail of pages that do not exist, which crawlers follow. Fall back on a default size when the size is not a positive integer, and bring the page back between 1 and the last page before passing them. #### The controls that are not links Two controls carry no destination and cannot navigate on their own: the "Go to page" form and the items per page [Select](https://ovh.github.io/design-system/v20.0.0/components/select). In link mode they report what the user asked for and wait, exactly as the pages do. The application turns that into a URL and navigates. ```tsx { const [searchParams] = useSearchParams(); const navigate = useNavigate(); const totalItems = 500; // The URL can hold anything: a size that is not a positive integer falls back on 10, and the // page is kept within the listing. const size = Number(searchParams.get('size')); const pageSize = Number.isSafeInteger(size) && size > 0 ? size : 10; const requestedPage = Number(searchParams.get('page')); const page = Number.isInteger(requestedPage) ? Math.min(Math.max(requestedPage, 1), Math.ceil(totalItems / pageSize)) : 1; // Merged into the current query, so that a sort or a filter it holds survives the navigation. function getPageUrl({ page, pageSize }: PaginationPageUrlDetail) { const params = new URLSearchParams(searchParams); params.set('page', String(page)); params.set('size', String(pageSize)); return `?${params}`; } // The pages are links and navigate on their own. // The two controls below are not, and have no href for the browser to follow: they report the // state they want, and the application navigates to the URL that describes it - the same URL // getPageUrl builds for the links. function handlePageChange({ page, pageSize }: PaginationPageChangeDetail) { navigate(getPageUrl({ page, pageSize })); } function handlePageSizeChange({ pageSize }: PaginationPageSizeChangeDetail) { navigate(getPageUrl({ page: 1, pageSize })); } return ( ); } ``` The **Pagination** does not move meanwhile, and that is deliberate. Were the items per page **Select** to apply the new size on its own, it would rebuild every `href` around a size the URL does not have yet, and the active page would fall outside a range that just shrank: the bar would show pages that no longer exist while the list beside it had not changed. Changing the size almost always means going back to the first page: under a new size the same page number shows other items, and may lie past the last page. That call belongs to the application, which is the one building the URL. #### Handing navigation to a router `getPageUrl` is enough on its own: the pages are plain anchors, and following one loads the destination the way any link does. On a server rendered site that is all you need. A single page application does want more, as a full document load would throw its state away. Pass the link component of your routing library as `linkAs`, and the pages navigate inside the app instead. It receives the built URL as `href`, so `next/link` takes it as is, while React Router's `Link` wants it as `to`: ```tsx { const [searchParams] = useSearchParams(); const totalItems = 500; // The URL can hold anything: a size that is not a positive integer falls back on 10, and the // page is kept within the listing. const size = Number(searchParams.get('size')); const pageSize = Number.isSafeInteger(size) && size > 0 ? size : 10; const requestedPage = Number(searchParams.get('page')); const page = Number.isInteger(requestedPage) ? Math.min(Math.max(requestedPage, 1), Math.ceil(totalItems / pageSize)) : 1; // Merged into the current query, so that a sort or a filter it holds survives the navigation. function getPageUrl({ page, pageSize }: PaginationPageUrlDetail) { const params = new URLSearchParams(searchParams); params.set('page', String(page)); params.set('size', String(pageSize)); return `?${params}`; } // Created once: a new component on every render would remount the links, and lose the focus // of the one just activated. In an application, declare it at module scope. const PaginationLink = useMemo(() => function PaginationLink({ href, ...props }: ComponentPropsWithRef<'a'> & { href: string }) { return ( ); }, []); return ( ); } ``` ## Navigation ### Focus Management When tabbing through the page, focus moves sequentially through all interactive elements in the **Pagination** component. In link mode the current page is exposed as a disabled link, out of the tab order. In Button mode it remains a focusable Button that does nothing when activated. Navigation controls that lead nowhere (e.g., “Previous” on the first page) are skipped in the tab order. ### General Keyboard Shortcuts Pressing `Tab` moves focus forward through all interactive elements in the **Pagination** (Select, page controls). Pressing `Shift` + `Tab` moves focus backward. When the pages are Buttons, pressing `Enter` or `Space` on a page, "Previous", or "Next" triggers the corresponding page change. When the pages are links, `Enter` follows the link, as on any anchor; `Space` scrolls the page instead. That difference comes from the elements themselves and is what users of either one expect. The "items per page" Select uses the same keyboard shortcuts as the standard Select component. ## Accessibility **Pagination** component should be properly identified, and correct labels must be implemented to ensure it is accessible to assistive technologies. ### Choosing between Buttons and links The choice is not a matter of style: it tells assistive technologies what activating a page does, and it is announced as such. Use the default **Buttons** when the pages are internal to the page the user is already on: activating one swaps a portion of the content, the URL does not change, and the user stays where they are. A screen reader announces a button, and the user expects to remain on the page. Use **links**, through `getPageUrl`, when a page is a destination of its own: activating one leaves the current document for another URL. A screen reader announces a link, and the user expects to be taken elsewhere. Rendering that as a Button would announce the wrong thing, and it would also deny the behaviours users expect from a link: opening in a new tab, copying the address, going back. > A page that navigates must never be a Button, and a page that only swaps content must never be a link. Announcing the wrong role sends the user somewhere they did not expect, or keeps them from getting where they wanted. ### Identifying the Pagination with aria-label **Pagination** is a form of navigation, but it serves a specific purpose distinct from primary navigation menus. To ensure it is correctly recognized, an [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) should be added to explicitly identify it. ```tsx ``` Screen readers will announce the pagination element correctly.