All components (204)

Load more button

Actions · LoadMoreButton

What it is and when to use it

The "Load more" of a paginated list, with the count underneath ("40 of 120 orders", with the language's numbers: "12,000 of 34,000"). What it contributes is not the button: it is that the result is announced. On pressing, focus stays on the button and the new rows appear below; without an announcement, whoever cannot see them finds out nothing.

When to use it

Lists and grids you keep scrolling down: the catalog, the order history, the photos of a gallery.
loaded is how many are loaded and name what is being counted ("orders"); text changes the button's text.
Without total if it is not known how many there are: it is always offered and the count only says how many are loaded.
onLoad can return a promise: the button waits, with the spinner, until it resolves.

When not to

When you have to jump to a specific page or go back to one: Pagination.
Thousands of rows that are already on the client: VirtualList.

Keyboard: Tab reaches the button; Enter and Space load. While loading it stays focusable, but does not respond again.

Accessibility: when loading finishes, the new count is announced in a status region. If it fails, it says so ("Could not load more. Please try again."), the button changes to "Retry" and the error goes to onError (or to the console, if none is passed). On reaching total the button goes away and endText remains, if given. If the button had focus, it does not fall to body: it moves to the first new element of list (the ul, the tbody or the grid, with one element per direct child) or, without it, to the final text or the count.

Fine-tuning: no variables of its own: it is adjusted with the classes amset-load, amset-load__count and amset-load__end. The button is a Button (with variant, tone and size) and accepts the --amset-button-* variables.

What it looks like

Order 1040
Order 1041
Order 1042
Order 1043
Order 1044

5 of 20 orders

<LoadMoreButton
  loaded={pedidos.length}
  total={20}
  name="orders"
  endText="No more orders"
  list={listaRef}
  onLoad={cargarOtros}
/>

Props

Import it with import { LoadMoreButton } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`loaded`required	`number`	—
`onLoad`required	`() => void \| Promise<void>`	Fetches the next chunk. If it returns a promise, the button waits.
`className`	`string`	Merged with the library classes; it does not replace them.
`endText`	`string`	Text for when nothing is left. Without this, nothing is drawn.
`list`	`RefObject<HTMLElement \| null>`	The list that keeps growing, with one element per direct child (the `ul`, the `tbody`, the grid). When the last page arrives the button goes away, and focus, if it had it, moves to the first new element. Without this it moves to the end text or, if there is none, to the count: it never falls to the `body`.
`name`	`string`	What the things being loaded are called: "results", "orders", "photos".
`onError`	`(error: unknown) => void`	What is done with the error if loading fails, besides saying it on screen: sending it to the application's log. Without this it goes to the console, since a failure that leaves no trace is never fixed.
`size`	`"sm" \| "md" \| "lg"`	—
`text`	`string`	—
`tone`	`"neutral" \| "accent" \| "secondary" \| "tertiary" \| "info" \| "success" \| "warning" \| "error"`	—
`total`	`number`	How many there are in total. Without this, the button does not know when to stop.
`variant`	`"solid" \| "soft" \| "outline" \| "ghost"`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: