Skip to main content

Pagination

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

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

The builder store used to create the pagination root.

The builder store used to create the pagination page trigger.

The builder store used to create the pagination previous button.

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.