Pagination

Page-navigation control for stepping through multi-page result sets.

Usage

<script lang="ts">
  import { Pagination } from '@lostgradient/cinder';

  let currentPage = $state(1);
</script>

<Pagination bind:currentPage totalPages={10} />

When the total page count is unknown, omit totalPages and pass the direction availability you know:

<script lang="ts">
  import { Pagination } from '@lostgradient/cinder';

  let currentPage = $state(1);
  let hasNextPage = $state(false);
</script>

<Pagination bind:currentPage hasPreviousPage={currentPage > 1} {hasNextPage} />

This renders the current page and previous/next controls without implying a fake final page.

REST Link headers

<script lang="ts">
  import { Pagination } from '@lostgradient/cinder';

  let currentPage = $state(1);
  let links = $state<{ prev?: string; next?: string }>({});
</script>

<Pagination
  bind:currentPage
  hasPreviousPage={links.prev !== undefined}
  hasNextPage={links.next !== undefined}
/>

Cursor pagination

Pass onPrevious and onNext to put the component in callback mode. The caller keeps the offset or cursors and is told when the user asks for the previous or next page; the component never changes currentPage.

<script lang="ts">
  import { Pagination } from '@lostgradient/cinder';

  let cursors = $state<{ previous?: string; next?: string }>({});

  function loadPage(cursor: string | undefined): void {
    // Fetch the page for this cursor and update `cursors`.
  }
</script>

<Pagination
  hasPreviousPage={cursors.previous !== undefined}
  hasNextPage={cursors.next !== undefined}
  onPrevious={() => loadPage(cursors.previous)}
  onNext={() => loadPage(cursors.next)}
/>

Callback mode

Giving onPrevious or onNext enables callback mode, which serves offset and cursor paging:

• Activating Previous or Next calls the callback with no arguments and leaves currentPage unchanged.
• Previous is enabled when onPrevious is given and hasPreviousPage is true, and Next when onNext is given and hasNextPage is true, so a list opened partway through can still go back. A direction with no callback stays disabled.
• No page-number buttons render. When totalPages is given, a "Page N of M" label shows between the buttons, using currentPage (default 1) for N; cursor paging without a total can omit currentPage.
• Without either callback, rendering and behavior are unchanged.

Custom count text

countLabel replaces the default "N results" text shown for totalCount. It receives the raw count, so format it yourself.

<Pagination totalPages={3} totalCount={1234} countLabel={(count) => `${count} runs`} />