Skip to content

Paged List

A button that adds the next page to a list, in place, without the page jumping.

TS
Tony Stark

rotated the API key prod-ingest

7m ago
AP
Ada Park

updated the billing email

14m ago
SR
Sam Rivera

invited sam@example.com

21m ago
PS
Priya Shah

turned on SSO

28m ago
JK
Jonah Kim

changed the plan to Team, billed yearly

35m ago

Showing 5 of 18

Installation

  1. Add the registryOnce per project
  2. Add paged-list

Usage

onLoadMore fetches the next page and adds it to your state. Return a promise so the button knows when loading is done. PagedListContent holds the rows, which are its direct children, in whatever markup suits them, such as an Item group, a list or a grid of cards. Pass render to make it a ul or a tbody. count is the number of rows shown, and passing it makes the count correct before the page loads its scripts. Without it, the rows are counted in the browser. locale formats the numbers in the count and in screen reader announcements.

When a page of rows arrives, the rows fade in and focus moves to the first new row, so someone using a keyboard or screen reader continues from where they asked for more. Screen readers also announce how many rows arrived. The button and count opt out of scroll anchoring, so new rows push them down rather than moving what users are reading. The Spinner shows only once a page has taken pendingDelay milliseconds, and then stays for at least minPending milliseconds, so it never flickers. While it shows, the button is disabled but keeps focus, and a second press while a page loads does nothing. Once hasMore is false, the button is replaced by a marker at the end of the list.

Composition

Examples

Errors

If onLoadMore rejects, the rows loaded so far stay, and the button offers to try again, with a message under it. In this example, the first attempt fails.

  • #4120main
  • #4119billing-flag
  • #4118sso-azure
  • #4117export-s3

Showing 4 of 12

Loading on scroll

auto loads the next page automatically when the button comes within 200 pixels of view, in the window or a scrolling container, so the list keeps going as users scroll. Focus stays where it is. After a failure, or a page that adds no rows, it waits for a press rather than loading again on its own.

Props

Base UI's styling (opens in a new tab) and composition (opens in a new tab) guides say more about className, style and render.

PagedList

PagedListContent

PagedListButton

PagedListCount

PagedListButton takes the props of Button too, and its children are its label while idle.

usePagedList

usePagedList() reads the PagedList that your component renders in, and returns its state: