Skip to content
BigBang

Popular

    ↑↓Navigate↵OpenEscClose
    TR

    Components

    Pagination

    Page or cursor navigation under tables and lists, with a page size choice.

    Storybook
    Storybook
    Source
    Source

    When to use

    Section titled “When to use”

    Pagination gives navigation under tables and lists that split many records into pages. Use numbered pages when the page count is known and cursor mode when it is not.

    When not to use

    Section titled “When not to use”
    • For few records: do not paginate a list that fits on one page.
    • For an endless feed: when users keep scrolling down, use a “Load more” button or a virtual list.
    • For a step-by-step flow: use Stepper for ordered steps; Pagination moves through records of the same kind.
    • For tabs: use Tabs for different views of content.

    Anatomy

    Section titled “Anatomy”
    1. Root (nav): a named navigation landmark.
    2. Page size (Pagination.PageSize): the “Per page” choice, optional.
    3. Summary (Pagination.Summary): “1-20 / 345”, optional.
    4. Previous, next (Pagination.Previous, Pagination.Next): chevron and text; the chevron alone on narrow screens.
    5. Page (Pagination.Page): a numbered control; the current page is selected.
    6. Ellipsis (Pagination.Ellipsis): skipped pages.
    7. Counter: “3 / 12” on narrow screens.

    Behaviour

    Section titled “Behaviour”
    • On a long list the page list keeps the same number of items on every page (2 × boundaryCount + 2 × siblingCount + 3), so controls do not shift.
    • Clicking the current page does nothing. Previous on the first page and next on the last page are inactive but stay focusable.
    • While disabled (for example while the next page loads) every control is inactive and stays focusable.
    • After a page change, focus stays on the clicked control. If that control goes away, focus moves to the current page.
    • Below 1024 px the page numbers are hidden; previous, next and the counter remain.
    • The summary text fades in briefly when the range changes.

    Guidelines

    Section titled “Guidelines”

    Reset the page when the size changes

    Section titled “Reset the page when the size changes”

    When the page size changes the current page may no longer exist. Set the page to 1 in onPageSizeChange.

    DoThe page returns to 1 when the size changes; the summary stays right.
    Don'tPage 9 is kept on a 5-page list: the component clamps it to 5 but you loaded data for the wrong page.

    Use a cursor when the page count is unknown

    Section titled “Use a cursor when the page count is unknown”

    When counting pages is expensive or impossible, do not show numbers.

    DoCursor mode: previous and next only.
    Don'tA made-up page count when the total is unknown.

    Hide it when there is one page

    Section titled “Hide it when there is one page”

    On a one-page list Pagination is noise; your app can show it when pageCount > 1.

    DoShown when there are several pages.
    Don'tTwo inactive arrows and one number for a single page.

    Content

    Section titled “Content”
    • Name the landmark with label; when a page has several Pagination components, give each a different name (“Result pages”).
    • Choose page size options from round numbers such as 10, 20, 50.
    • Pagination formats the numbers with Intl; the Provider sets the language.
    • The library strings (Previous, Next, Page 3) follow the Provider language.
    Section titled “Related components”
    • Select: the “Per page” choice is built with it.
    • Button: the base of the page and chevron controls.
    • Table: the table Pagination sits under.