Navigation

Pagination

Page-number control for paged result sets that exposes previous, next, and numeric jumps with elided middle pages.

import { Pagination } from '@lostgradient/cinder/pagination';
navigationpaging
01

Overview

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

Usage

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

  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:

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

  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

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

  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

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

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

<Pagination
  bind:currentPage
  hasPreviousPage={cursors.previous !== undefined}
  hasNextPage={cursors.next !== undefined}
/>
Live preview
02

When to use

Use when
  • Moving through a large, ordered dataset split into discrete pages of fixed size.
  • Showing the current page in context of the total page count.
Avoid when
  • Switching between named sibling views — use tabs instead.
  • Streaming results as the user scrolls — wire up infinite scroll directly.
03

Examples

Basic pagination

Navigate through pages with previous/next and numbered buttons.

Cursor pagination

Use page-local cursor metadata when an API exposes previous and next cursors instead of totals.

Pagination with total count

totalCount prop shows formatted record count.

04

Props

Props for pagination
Name Type Default Required Bindable Description
currentPage number 1 bind Current page number (1-indexed). Bindable.
totalPages number Total number of pages. Omit when only previous/next availability is known.
hasPreviousPage boolean Whether a previous page is available when totalPages is unknown. Defaults to currentPage > 1.
hasNextPage boolean false Whether a next page is available when totalPages is unknown. Defaults to false.
totalCount number Optional total record count; formatted with formatNumber when provided.