Pagination

An interface that allows navigating between pages that contain split entries.

View code

Features

Full keyboard navigation support
Supports a custom number of pages
Display range of visible pages
Supports a custom number of visible pages
Supports a custom number of sibling pages

Anatomy

Root: The root container for the pagination component
Previous Button: The button which navigates to the previous page
Page Trigger: The button(s) which navigates to a specific page
Next Button: The button which navigates to the next page
Range: The range of pages that are visible to the user

Usage

To create a pagination component, use the createPagination builder function. Follow the anatomy or the example above to create your pagination component.

    <script lang="ts">
  import { createPagination, melt } from '@melt-ui/svelte'
  const {
    elements: { root, pageTrigger, prevButton, nextButton },
    states: { pages, range }
  } = createPagination({
    count: 100,
    perPage: 10,
    defaultPage: 1,
    siblingCount: 1
  })
</script>
 
<nav use:melt={$root}>
  <p>Showing items {$range.start} - {$range.end}</p>
  <div>
    <button use:melt={$prevButton}>Prev</button>
    {#each $pages as page (page.key)}
      {#if page.type === 'ellipsis'}
        <span>...</span>
      {:else}
        <button use:melt={$pageTrigger(page)}>{page.value}</button>
      {/if}
    {/each}
    <button use:melt={$nextButton}>Next</button>
  </div>
</nav>

    <script lang="ts">
  import { createPagination, melt } from '@melt-ui/svelte'
  const {
    elements: { root, pageTrigger, prevButton, nextButton },
    states: { pages, range }
  } = createPagination({
    count: 100,
    perPage: 10,
    defaultPage: 1,
    siblingCount: 1
  })
</script>
 
<nav {...$root} use:root>
  <p>Showing items {$range.start} - {$range.end}</p>
  <div>
    <button {...$prevButton} use:prevButton>Prev</button>
    {#each $pages as page (page.key)}
      {#if page.type === 'ellipsis'}
        <span>...</span>
      {:else}
        <button {...$pageTrigger(page)} use:pageTrigger>{page.value}</button>
      {/if}
    {/each}
    <button {...$nextButton} use:nextButton>Next</button>
  </div>
</nav>

API Reference

createPagination

The builder function used to create the pagination component.

Props

Prop	Default	Type / Description
`count`	-	`number` The total number of items.
`perPage`	`1`	`number` The number of items per page.
`siblingCount`	`1`	`number` The number of page triggers to show on either side of the current page.
`defaultPage`	`1`	`number` The default page number.
`page`	-	`Writable<number>` A writable store that controls the current page. See Bring Your Own Store
`onPageChange`	-	`ChangeFn<number>` A callback called when the page of the `page` store should be changed. This is useful for controlling the page of the pagination from outside the pagination. See Change Functions

Elements

Element	Description
`root`	The builder store used to create the pagination root.
`pageTrigger`	The builder store used to create the pagination page trigger.
`prevButton`	The builder store used to create the pagination previous button.
`nextButton`	The builder store used to create the pagination next button.

States

State	Description
`range`	A readable store that contains the start and end page numbers.
`pages`	A readable store that contains the page items.
`totalPages`	A readable store that contains the total number of pages.
`page`	A writable store that contains the current page number.

Options

Option	Description
`count`	The total number of items.
`perPage`	The number of items per page.
`siblingCount`	The number of page triggers to show on either side of the current page.

root

The root element of the pagination component.

Data Attributes

Data Attribute	Value
`[data-scope]`	`pagination`
`[data-melt-pagination]`	Present on all pagination elements.

pageTrigger

A button that triggers a page change.

Data Attributes

Data Attribute	Value
`[data-selected]`	Present when the page is selected.
`[data-melt-pagination-page-trigger]`	Present on all pageTrigger elements.

Custom Events

Event	Value
`m-click`	`(e: ) => void`
`m-keydown`	`(e: ) => void`

prevButton

A button that moves to the previous page.

Data Attributes

Data Attribute	Value
`[data-melt-pagination-prev-button]`	Present on all prevButton elements.

Custom Events

Event	Value
`m-click`	`(e: ) => void`
`m-keydown`	`(e: ) => void`

nextButton

A button that moves to the next page.

Data Attributes

Data Attribute	Value
`[data-melt-pagination-next-button]`	Present on all nextButton elements.

Custom Events

Event	Value
`m-click`	`(e: ) => void`
`m-keydown`	`(e: ) => void`

Accessibility

Adheres to the a11y Accessible Pagination guidelines

Key	Behavior
`Space`	When focused on a `pageTrigger` or `nextButton`, moves to that page.
`Enter`	When focused on a `pageTrigger` or `nextButton`, moves to that page.
`Tab`	Moves focus to the next focusable element.
`Shift + Tab`	Moves focus to the previous focusable element
`ArrowRight`	Moves focus to the next focusable `pageTrigger` or `nextButton`.
`ArrowLeft`	Moves focus to the previous focusable `pageTrigger` or `prevButton`
`Home`	Moves focus to the first focusable `pageTrigger` or `prevButton`.
`End`	Moves focus to the first focusable `pageTrigger` or `prevButton`.

On This Page