Paginator

When to use

Large Datasets

When there is too much data to display within a single page or component view, and you want to break it into manageable chunks so users can scan, compare, and keep their place more easily. Also when loading all available data at once would be slow, heavy or resource-intensive, and you need to keep performance predictable.

Precise Navigation

When users need explicit control over where they are in a list, for example, jumping to a specific page, returning to a remembered page number, or sharing a URL that always opens the same subset of results.

When not to use

Linear Journeys Flows

For multi-step processes such as forms, wizards, or checkout flows where the user should move forward or backward step by step. In these cases, use buttons or a progress indicator instead of paginator.

Short, Small, or Simple Content

When the content fits comfortably on a single page without performance issues, or when the dataset is small gives a simpler, more natural experience.

Anatomy

Page Size

Control that lets users choose how many items are shown per page. Changing this value recalculates the total number of pages.

Paginator

The main navigation for moving across pages.

Status

Text that communicates where the user is in the full result set, typically:

Widths

Control how many page buttons are visible at once before pages are moved into the overflow menu.

• LG: Shows up to 13 page items in a single row.
• MD: Shows up to 11 page items.
• SM: Shows up to 9 page items.
• XS: When the available space is very limited, page buttons are replaced by a single select field so users can pick a page from a dropdown.

Use wider versions when the Paginator is a primary control, for example, at the bottom of a data table and narrower versions when space is constrained or the pagination is secondary.

Emphasis

The Paginator supports two emphasis levels:

• Subtle: Low-contrast styling that keeps pagination in the background while still discoverable. Use when pagination is supportive, not the main focus of the page.
• Bold: Higher visual weight for cases where pagination is a primary navigation element or is critical to the user’s workflow.

Choose the emphasis that matches the visual hierarchy of surrounding content.

Sizes

The Paginator offers three control sizes:

• Large: For dense layouts, large data tables or touch-first experiences where targets need to be easier to hit.
• Medium: The default size for most use cases and general content pages.
• Small: For compact layouts, side panels, or areas where vertical space is limited.

Ideally, match the Paginator size to the height of related controls, for example, table rows or filter inputs.

Figma Options

With these options, you can tweak the appearance of the paginator in Figma. They are available in the Design Panel so you can compose the paginator to exactly fit the user experience need for the use case you are working on.

Paginator

Paginator Status

Paginator Size

Behaviours

Keyboard navigation

Users can move through the Paginator with the keyboard using Tab and Shift+Tab to follow a logical focus order across controls, and use Enter or Space to activate Previous and Next, select a page, or open and confirm options in overflow menus, while arrow keys help navigate within any the overflow dropdown.

Overflow pages

When there are more pages than can be shown at once, hidden pages are moved into an overflow menu represented by an ellipsis, which adapts depending on the current page (start or end of the range) while keeping the overall layout stable and avoiding any width changes.

Responsive behaviour

On larger viewports, the Paginator can show more page buttons alongside Previous and Next, while on smaller or constrained layouts it reduces the number of visible pages and, at the narrowest widths, can replace numbered buttons with a page select field to keep pagination usable and readable on mobile.

Related components

• Text Field: If you want a free-form text input.
• Select: Selecting from predefined numeric options.

Using data source with paginator

A data source is an interface that manages data fetching, state, and pagination logic. It allows you to connect paginator components to your data in a consistent way, whether that data comes from an API, an in memory array, or any other source.

Setting up a data source

To use a data source with the paginator components, follow these steps:

1. Create a data source instance - Use FetchListDataSource for API based data or ArrayListDataSource for in memory arrays. You can also implement your own data source by extending the ListDataSource class and implementing the required methods.
2. Configure pagination settings - Set pageSize and enable pagination.
3. Implement data fetching - Define the fetchPage method to retrieve data for each page (for API based data).
4. Connect to components - Assign the same data source instance to sl-paginator, sl-paginator-status, and sl-paginator-page-size.

Example

const ds = new FetchListDataSource({
  pageSize: 10,
  pagination: true,
  fetchPage: async ({ page, pageSize }) => {
    const response = await fetch(
      `https://api.example.com/data?skip=${page * pageSize}&limit=${pageSize}`
    );
    
    if (response.ok) {
      const { items, total } = await response.json();
      return { items, totalItems: total };
    } else {
      throw new FetchListDataSourceError('Failed to fetch data', response);
    }
  }
});

// Connect the data source to all paginator components
paginatorStatus.dataSource = ds;
paginator.dataSource = ds;
pageSize.dataSource = ds;

Once connected, the paginator components will automatically:

• Display the correct page information
• Fetch new data when users navigate between pages
• Update when the page size changes
• Show the total number of items and current range

Paginator page size API

Paginator page size component provides properties to configure available page size options and current selection.

Properties

Events

Paginator API

The paginator component offers settings for various scenarios.

Properties

Events

Paginator status API

Paginator status component displays pagination information using page, pageSize, and totalItems properties.

Properties

Keyboard interactions

The paginator provides full keyboard navigation to move between the pages of a list:

Announcements

The paginator provides screen reader announcements for important state changes:

• Page changes: When navigating between pages using previous/next buttons or selecting a page directly, the new page number and total pages are announced.
• Page size changes: When changing the number of items per page, the new page size is announced to inform users of the updated display.
• Status updates: When the page, page size, or total items change, the current page range and total item count are immediately announced to screen readers to provide context about the displayed content.

These announcements help users understand pagination changes without needing to navigate back to check the current state.

WAI-ARIA

In the component itself we use multiple aria-attributes to assure the component works well with a range of assistive technologies. For some attributes however it is not possible for the Design System to add a meaningful value, because it relies on the context or way a component is used.

Attributes that we recommend you add in certain scenarios are mentioned below.

Paginator