Break up long lists
Use pagination when a list or table spans more results than one page should show.
Components
Pagination
The pagination component enables the user to select a specific page from a range of pages.
Show current position
The current page indicator helps users understand where they are in the set.
Control result browsing
Pair with page size controls when users need to change how many results they see.
1
Previous navigation
2
Active page
3
Page number
4
Overflow icon
5
Next navigation
Variant
Pagination supports four visual styles. Choose the variant that best fits your layout density and the user task.
First, last and page-direction buttons with a window of page numbers and ellipses.
Size
Match the pagination scale to the surrounding UI density.
Default size suitable for most pages.
Current page
Sets the active page on first render.
Mid-range page reveals leading and trailing ellipses.
Navigation
Pagination can show number-only navigation or include previous and next controls.
Use page numbers when direct page access matters and previous/next controls are not needed.
Result count
Data length and items per page determine how many pages are rendered.
Use dataLength and itemsPerPage to match the number of records being paginated.
Design tokens used
Each row is a colour, spacing, or size value the component uses, and the right-most column tells you where in the component you'll see it.
sgds-gap-2-xs4pxsgds-border-radius-md8pxsgds-dimension-4848pxsgds-outline-focus—sgds-outline-offset-focus—When to use
- Use pagination when showing everything on one page would hurt performance or make results difficult to scan.
- Use it when users need a predictable way to move through related pages of results.
When not to use
- Do not use pagination when there is only one page of content.
- Do not use it for step-by-step journeys where users should move forward with a button and back link instead.
Use pagination for large, browsable result sets
Pagination suits tables and lists with many entries. Set itemsPerPage to fit the surrounding layout.
Do not paginate very small lists
If the full list fits on one page, omit pagination. A single-page control only adds visual noise.
Use the button variant for sequential flows
When users only need previous and next controls, like a guided tour, the button variant keeps the UI clean.
Loading more results as you scroll...
Do not pair pagination with infinite scroll
Pagination and infinite scroll conflict on how data loads. Pick one pattern per surface.
Built-in accessibility
- Pagination renders a navigation region and page controls with current-page state.
- Page controls expose labels for their destination pages.
Labels and content
- Use pagination when users need to move through a known set of pages.
- Keep the current page state accurate when data changes.
Focus and interaction
- Users should be able to tab through available page controls.
- Disabled previous or next controls should not block users from reaching page numbers.
TabShift+TabEnterHave suggestions or feedback?
Share them with us on Slack → #ask-sgds-v3
Found a bug or issue?
Report it on GitHub Issues → sgds/components/pagination