Report an issue

Pagination

Facilitates navigation between pages.

...

Showing 0 - 10

	<script lang="ts">
  import { Pagination } from "bits-ui";
  import CaretLeft from "phosphor-svelte/lib/CaretLeft";
  import CaretRight from "phosphor-svelte/lib/CaretRight";
</script>
 
<Pagination.Root count={100} perPage={10}>
  {#snippet children({ pages, range })}
    <div class="my-8 flex items-center">
      <Pagination.PrevButton
        class="mr-[25px] inline-flex size-10 items-center justify-center rounded-[9px] bg-transparent hover:bg-dark-10 active:scale-98 disabled:cursor-not-allowed disabled:text-muted-foreground hover:disabled:bg-transparent"
      >
        <CaretLeft class="size-6" />
      </Pagination.PrevButton>
      <div class="flex items-center gap-2.5">
        {#each pages as page (page.key)}
          {#if page.type === "ellipsis"}
            <div class="text-[15px] font-medium text-foreground-alt">...</div>
          {:else}
            <Pagination.Page
              {page}
              class="inline-flex size-10 items-center justify-center rounded-[9px] bg-transparent text-[15px] font-medium hover:bg-dark-10 active:scale-98 disabled:cursor-not-allowed disabled:opacity-50 hover:disabled:bg-transparent data-[selected]:bg-foreground data-[selected]:text-background"
            >
              {page.value}
            </Pagination.Page>
          {/if}
        {/each}
      </div>
      <Pagination.NextButton
        class="ml-[29px] inline-flex size-10 items-center justify-center rounded-[9px] bg-transparent hover:bg-dark-10 active:scale-98 disabled:cursor-not-allowed disabled:text-muted-foreground hover:disabled:bg-transparent"
      >
        <CaretRight class="size-6" />
      </Pagination.NextButton>
    </div>
    <p class="text-center text-[13px] text-muted-foreground">
      Showing {range.start} - {range.end}
    </p>
  {/snippet}
</Pagination.Root>

Structure

	<script lang="ts">
	import { Pagination } from "bits-ui";
</script>
 
<Pagination.Root let:pages>
	<Pagination.PrevButton />
	{#each pages as page (page.key)}
		<Pagination.Page {page} />
	{/each}
	<Pagination.NextButton />
</Pagination.Root>

Page State

Bits UI provides flexible options for controlling and synchronizing the component's page state.

Two-Way Binding

Use the bind:page directive for effortless two-way synchronization between your local state and the component's internal state.

	<script lang="ts">
	import { Pagination } from "bits-ui";
	let myPage = $state(1);
</script>
 
<button onclick={() => (myPage = 10)}>Go to page 10</button>
 
<Pagination.Root bind:page={myPage}>
	<!-- ... -->
</Pagination.Root>

This setup enables changing the page via the custom button and ensures the local myPage state updates when the state updates through any internal means.

Change Handler

You can also use the onPageChange prop to update local state when the component's page state changes. This is useful when you don't want two-way binding for one reason or another, or you want to perform additional logic when the page changes.

	<script lang="ts">
	import { Pagination } from "bits-ui";
	let myPage = $state(1);
</script>
 
<Pagination.Root
	page={myPage}
	onPageChange={(newPage) => {
		myPage = newPage;
		// additional logic here.
	}}
>
	<!-- ... -->
</Pagination.Root>

Controlled

Sometimes, you may want complete control over the component's page state, meaning you will be "kept in the loop" and be required to apply the state change yourself. While you'll rarely need this, it's possible to do so by setting the controlledPage prop to true.

You will then be responsible for updating a local state variable that is passed as the page prop to the Pagination.Root component.

	<script lang="ts">
	import { Pagination } from "bits-ui";
 
	let myPage = $state(1);
</script>
 
<Pagination.Root controlledPage page={myPage} onPageChange={(p) => (myPage = p)}>
	<!-- ... -->
</Pagination.Root>

See the Controlled State documentation for more information about controlled states.

Ellipsis

The pages snippet prop consists of two types of items: 'page' and 'ellipsis'. The 'page' type represents an actual page number, while the 'ellipsis' type represents a placeholder for rendering an ellipsis between pages.

API Reference

Pagination.Root

The root pagination component which contains all other pagination components.

Property Type Description
count required
number

The total number of items.

Default: undefined
page $bindable
number

The selected page. You can bind this to a variable to control the selected page from outside the component.

Default: undefined
onPageChange
function

A function called when the selected page changes.

Default: undefined
controlledPage
boolean

Whether or not the page state is controlled or not. If true, the component will not update the page state internally, instead it will call onPageChange when it would have otherwise, and it is up to you to update the page prop that is passed to the component.

Default: false
perPage
number

The number of items per page.

Default: 1
siblingCount
number

The number of page triggers to show on either side of the current page.

Default: 1
loop
boolean

Whether or not the pagination should loop through the items when reaching the end while navigating with the keyboard.

Default: false
orientation
enum

The orientation of the pagination. This determins how keyboard navigation will work with the component.

Default: horizontal
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined

Pagination.Page

A button that triggers a page change.

Property Type Description
page
PageItem

The page item this component represents.

Default: undefined
ref $bindable
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-selected
''

Present on the current page element.

data-pagination-page
''

Present on the page trigger element.

Pagination.PrevButton

The previous button of the pagination.

Property Type Description
ref $bindable
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-pagination-prev-button
''

Present on the previous button element.

Pagination.NextButton

The next button of the pagination.

Property Type Description
ref $bindable
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-pagination-next-button
''

Present on the next button element.