# Pagination Documentation
Facilitates navigation between pages.
This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.
```svelte
{#snippet children({ pages, range })}
{#each pages as page (page.key)}
{#if page.type === "ellipsis"}
...
{:else}
{page.value}
{/if}
{/each}
Showing {range.start} - {range.end}
{/snippet}
```
## Structure
```svelte
{#each pages as page (page.key)}
{/each}
```
## Managing Page State
This section covers how to manage the `page` state of the component.
### Two-Way Binding
Use `bind:page` for simple, automatic state synchronization:
```svelte
```
### Fully Controlled
Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.
```svelte
```
## 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 | Details |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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`- (page: number) =\> void | A function called when the selected page changes.`Default: undefined` | |
| `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`- 'horizontal' \| 'vertical' | The orientation of the pagination. This determines 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: null` | |
| `children` | `Snippet`- type Page = \{ type: "page"; value: number; \}; type Ellipsis = \{ type: "ellipsis"; \}; type PageItem = (Page \| Ellipsis) & \{ /\*\* A unique key to be used as the key in a svelte #each block. \*/ key: string; \}; type ChildrenSnippetProps = \{ /\*\* The items to iterate over and render for the pagination component \*/ pages: PageItem\[]; /\*\* The range of pages to render \*/ range: \{ start: number; end: number \}; /\*\* The currently active page \*/ currentPage: number; \}; | The children content to render.`Default: undefined` | |
| `child` | `Snippet`- type Page = \{ type: "page"; value: number; \}; type Ellipsis = \{ type: "ellipsis"; \}; type PageItem = (Page \| Ellipsis) & \{ /\*\* A unique key to be used as the key in a svelte #each block. \*/ key: string; \}; type ChildSnippetProps = \{ /\*\* The items to iterate over and render for the pagination component \*/ pages: PageItem\[]; /\*\* The range of pages to render \*/ range: \{ start: number; end: number \}; /\*\* The currently active page \*/ currentPage: number; props: Record\<string, unknown\>; \}; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | | Data Attribute | Value | Description | Details |
| ------------------------------------------------- | --------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ### Pagination.Page
A button that triggers a page change.
| Property | Type | Description | Details |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page` | `PageItem`- export type Page = \{ type: "page"; /\*\* The page number the 'PageItem' represents \*/ value: number; \} export type Ellipsis = \{ type: "ellipsis"; \} export type PageItem = (Page \| Ellipsis) & \{ /\*\* Unique key for the item, for svelte #each block \*/ key: string; \} | 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: null` | |
| `children` | `Snippet` | The children content to render.`Default: undefined` | |
| `child` | `Snippet`- type SnippetProps = \{ props: Record\<string, unknown\>; \}; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | | Data Attribute | Value | Description | Details |
| ------------------------------------------------------------------------ | ------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 | Details |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | |
| `children` | `Snippet` | The children content to render.`Default: undefined` | |
| `child` | `Snippet`- type SnippetProps = \{ props: Record\<string, unknown\>; \}; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | | Data Attribute | Value | Description | Details |
| -------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-pagination-prev-button` | `''` | Present on the previous button element. | |
### Pagination.NextButton
The next button of the pagination.
| Property | Type | Description | Details |
| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ref` $bindable | `HTMLButtonElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | |
| `children` | `Snippet` | The children content to render.`Default: undefined` | |
| `child` | `Snippet`- type SnippetProps = \{ props: Record\<string, unknown\>; \}; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | | Data Attribute | Value | Description | Details |
| -------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-pagination-next-button` | `''` | Present on the next button element. | |