Pagination
kumo-svelte

Pagination

A page navigation component for navigating through paginated content.

Showing 1-10 of 100
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }
</script>

<Pagination page={paginationPage} setPage={setPaginationPage} perPage={10} totalCount={100} />

Installation

Barrel

import { Pagination, PaginationControls, PaginationInfo, PaginationPageSize, PaginationSeparator } from 'kumo-svelte';

Granular

import { Pagination, PaginationControls, PaginationInfo, PaginationPageSize, PaginationSeparator } from 'kumo-svelte/components/pagination';

Usage

<script lang="ts">  import { Pagination } from 'kumo-svelte';  let page = $state(1);</script><Pagination bind:page perPage={10} totalCount={100} />

Examples

Full Controls (Default)

The default pagination includes first, previous, page input, next, and last buttons.

Showing 1-10 of 100
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }
</script>

<Pagination page={paginationPage} setPage={setPaginationPage} perPage={10} totalCount={100} controls="full" />

Simple Controls

Use controls="simple" for a minimal pagination with only previous and next buttons.

Showing 1-10 of 100
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }
</script>

<Pagination page={paginationPage} setPage={setPaginationPage} perPage={10} totalCount={100} controls="simple" />

Mid-Page State

Pagination in the middle of a dataset with all navigation enabled.

Showing 41-50 of 100
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(5);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }
</script>

<Pagination page={paginationPage} setPage={setPaginationPage} perPage={10} totalCount={100} />

Large Dataset

Pagination handles large datasets with many pages.

Showing 1-25 of 1250
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }
</script>

<Pagination page={paginationPage} setPage={setPaginationPage} perPage={25} totalCount={1250} />

Custom Text

You can set custom pagination text.

Page 1 - showing 25 per page
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }
</script>

<Pagination
  text={({ perPage }) => `Page ${paginationPage} - showing ${perPage} per page`}
  page={paginationPage}
  setPage={setPaginationPage}
  perPage={25}
  totalCount={100}
/>

Compound Components

For more control over layout and features, use the compound component API. This allows you to compose Pagination.Info, Pagination.PageSize, Pagination.Controls, and Pagination.Separator in any order.

Import the compound pieces from the package barrel:

<script lang="ts">  import { Pagination } from 'kumo-svelte';  let page = $state(1);  let perPage = $state(25);</script><Pagination bind:page {perPage} totalCount={500}>  <Pagination.Info />  <Pagination.Separator />  <Pagination.PageSize bind:value={perPage} onChange={(size) => {    perPage = size;    page = 1;  }} />  <Pagination.Controls /></Pagination>

Page Size Selector

Add a dropdown to let users select the number of items per page.

Showing 1-25 of 500
Per page: 
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);
  let paginationPerPage = $state(25);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }

  function setPaginationPerPage(nextPerPage: number) {
    paginationPerPage = nextPerPage;
  }
</script>

<Pagination page={paginationPage} setPage={setPaginationPage} perPage={paginationPerPage} totalCount={500}>
  <Pagination.Info />
  <Pagination.Separator />
  <Pagination.PageSize
    value={paginationPerPage}
    onChange={(size) => {
      setPaginationPerPage(size);
      setPaginationPage(1);
    }}
  />
  <Pagination.Controls />
</Pagination>

Custom Page Size Options

Customize the available page size options with the options prop. Defaults to [25, 50, 100, 250].

Showing 1-10 of 200
Per page: 
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);
  let paginationPerPage = $state(10);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }

  function setPaginationPerPage(nextPerPage: number) {
    paginationPerPage = nextPerPage;
  }
</script>

<Pagination page={paginationPage} setPage={setPaginationPage} perPage={paginationPerPage} totalCount={200}>
  <Pagination.Info />
  <Pagination.Separator />
  <Pagination.PageSize
    value={paginationPerPage}
    onChange={(size) => {
      setPaginationPerPage(size);
      setPaginationPage(1);
    }}
    options={[10, 20, 50]}
  />
  <Pagination.Controls />
</Pagination>

Custom Info Text

Use a render function to customize the info text.

Page 1 of 4
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }
</script>

<Pagination page={paginationPage} setPage={setPaginationPage} perPage={25} totalCount={100}>
  <Pagination.Info>
    {#snippet children({ page, totalCount })}
      Page {page} of {Math.ceil((totalCount ?? 1) / 25)}
    {/snippet}
  </Pagination.Info>
  <Pagination.Controls />
</Pagination>

Custom Layout

Arrange components in any order. Here the page size selector is on the right.

Showing 1-25 of 500
Per page: 
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);
  let paginationPerPage = $state(25);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }

  function setPaginationPerPage(nextPerPage: number) {
    paginationPerPage = nextPerPage;
  }
</script>

<Pagination page={paginationPage} setPage={setPaginationPage} perPage={paginationPerPage} totalCount={500}>
  <Pagination.Info />
  <div class="flex items-center gap-2">
    <Pagination.Controls />
    <Pagination.Separator />
    <Pagination.PageSize
      value={paginationPerPage}
      onChange={(size) => {
        setPaginationPerPage(size);
        setPaginationPage(1);
      }}
    />
  </div>
</Pagination>

Dropdown Page Selector

Use pageSelector="dropdown" on Pagination.Controls to render a dropdown select instead of a text input for page navigation. This is useful when you want users to pick from a list of available pages rather than typing a number.

Showing 1-25 of 500
Per page: 
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);
  let paginationPerPage = $state(25);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }

  function setPaginationPerPage(nextPerPage: number) {
    paginationPerPage = nextPerPage;
  }
</script>

<Pagination page={paginationPage} setPage={setPaginationPage} perPage={paginationPerPage} totalCount={500}>
  <Pagination.Info />
  <Pagination.Separator />
  <Pagination.PageSize
    value={paginationPerPage}
    onChange={(size) => {
      setPaginationPerPage(size);
      setPaginationPage(1);
    }}
  />
  <Pagination.Controls pageSelector="dropdown" />
</Pagination>

Internationalization

Use the labels prop to customize all UI strings for different locales. All labels default to English.

Affichage de 1-10 sur 100
<script lang="ts">
  import { Pagination } from '$lib';

  let paginationPage = $state(1);

  function setPaginationPage(nextPage: number) {
    paginationPage = nextPage;
  }
</script>

<Pagination
  page={paginationPage}
  setPage={setPaginationPage}
  perPage={10}
  totalCount={100}
  labels={{
    firstPage: 'Première page',
    previousPage: 'Page précédente',
    nextPage: 'Page suivante',
    lastPage: 'Dernière page',
    pageNumber: 'Numéro de page',
    pageSize: 'Taille de page'
  }}
>
  <Pagination.Info>
    {#snippet children({ pageShowingRange, totalCount })}
      Affichage de <span class="tabular-nums">{pageShowingRange}</span> sur
      <span class="tabular-nums">{totalCount}</span>
    {/snippet}
  </Pagination.Info>
  <Pagination.Controls />
</Pagination>

API Reference

PropTypeDefaultDescription
setPage *(page: number) => void-Callback fired when the current page changes. In Svelte, bind:page can be used instead.
page number1Current page number (1-indexed).
perPage number-Number of items displayed per page.
totalCount number-Total number of items across all pages.
class string-Additional classes merged onto the root element.
labels PaginationLabels-Labels for internationalization of aria-labels.
children Snippet-Compound component children for custom layouts.
controls 'full' | 'simple'"full"Legacy API control density.
text (props: { page?: number; perPage?: number; totalCount?: number; pageShowingRange: string }) => unknown-Deprecated legacy render function for the info text. Prefer Pagination.Info children.