> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/pagination.md).

# Pagination

`avonni-pagination`

A navigation control that displays numbered page buttons alongside previous, next and bookend controls, and fires an event with the selected page number.

## Overview

**Pagination** is a Lightning Web Component that renders a row of numbered page buttons together with previous, next and bookend controls, and reports the page the user picked.

Use it in your own Lightning Web Components whenever a dataset is too large to render at once. The component owns no data: you give it the size of the dataset and the page size, it works out how many pages there are, and it tells you which page the user selected so your component can fetch or slice the matching records.

### Use Cases

* **Paged record lists:** Step through a large query result a screenful at a time.
* **Paged tables:** Drive a custom table's offset from the selected page number.
* **Search results:** Let users move through result pages without scrolling.
* **Compact layouts:** Cap the number of visible buttons and collapse the rest behind an ellipsis.
* **Read-only states:** Disable the whole control while a page is loading.

***

## Alignment Guidelines

| Alignment | Use Case                                                      |
| --------- | ------------------------------------------------------------- |
| `left`    | Default; pagination sits under a left-aligned list or table.  |
| `center`  | Centred layouts, such as a card footer.                       |
| `right`   | Pairs with right-aligned footer actions.                      |
| `fill`    | Buttons stretch to fill the available width of the container. |

***

## Use Case Examples

### Example 1: Paging through a record list

**Scenario:** Show 20 records at a time from a 200-record dataset and reload the list when the user picks another page.

```html
<!-- recordPager.html -->
<template>
    <avonni-pagination
        total-rows="200"
        per-page="20"
        value={currentPage}
        onchange={handlePageChange}
    ></avonni-pagination>
</template>
```

```js
// recordPager.js
import { LightningElement } from 'lwc';

export default class RecordPager extends LightningElement {
    currentPage = 1;

    handlePageChange(event) {
        this.currentPage = Number(event.detail.value);
        // Fetch or slice the records for this.currentPage.
    }
}
```

**Result:** Ten page buttons' worth of data, five buttons visible at a time, with the rest collapsed behind an ellipsis. Selecting a page fires `change` and hands you the new page number.

### Example 2: Labelled navigation buttons

**Scenario:** Replace the default chevrons with labelled previous, next and bookend buttons in a wide footer.

```html
<!-- catalogPager.html -->
<template>
    <avonni-pagination
        align="center"
        total-rows="100"
        per-page="10"
        first-button-label="First"
        first-button-icon-name="utility:jump_to_left"
        previous-button-label="back"
        previous-button-icon-name="utility:back"
        next-button-label="next"
        next-button-icon-name="utility:forward"
        last-button-label="Last"
        last-button-icon-name="utility:jump_to_right"
        onchange={handlePageChange}
    ></avonni-pagination>
</template>
```

**Result:** A centred control with named bookend buttons. Setting a label on the previous or next button replaces its default chevron icon, so supply an icon name alongside the label if you still want one.

***

## Specifications

### Attributes

| Name                        | Description                                                                                                                 | Type    | Default                  | Required |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------ | -------- |
| `align`                     | Alignment of the page buttons. Values include left, center, right and fill.                                                 | String  | `"left"`                 |          |
| `disable-ellipsis`          | If present, the ellipsis (…) buttons are disabled, even when the rest of the pagination remains enabled.                    | Boolean | `false`                  |          |
| `disabled`                  | If present, the pagination is disabled and the user cannot interact with it.                                                | Boolean | `false`                  |          |
| `ellipsis-text`             | Content to place in the ellipsis placeholder.                                                                               | String  | `"..."`                  |          |
| `first-button-icon-name`    | The name of an icon to display after the label of the first button.                                                         | String  | —                        |          |
| `first-button-label`        | Label for the first button.                                                                                                 | String  | —                        |          |
| `last-button-icon-name`     | The name of an icon to display after the label for the last button.                                                         | String  | —                        |          |
| `last-button-label`         | Label for the last button.                                                                                                  | String  | —                        |          |
| `limit`                     | Maximum number of buttons to show (including ellipsis if shown, but excluding the bookend buttons). The minimum value is 3. | Number  | `5`                      |          |
| `next-button-icon-name`     | The name of an icon to display after the label for the next button.                                                         | String  | `"utility:chevronright"` |          |
| `next-button-label`         | Label for the next button.                                                                                                  | String  | —                        |          |
| `per-page`                  | Number of rows per page                                                                                                     | Number  | `20`                     |          |
| `previous-button-icon-name` | The name of an icon to display after the label for the previous button.                                                     | String  | `"utility:chevronleft"`  |          |
| `previous-button-label`     | Label for the previous button.                                                                                              | String  | —                        |          |
| `total-rows`                | Total number of rows in the dataset.                                                                                        | Number  | `0`                      |          |
| `value`                     | Current page number, starting from 1                                                                                        | Number  | `1`                      |          |

### Methods

| Name       | Description          | Argument Name | Argument Type | Argument Description |
| ---------- | -------------------- | ------------- | ------------- | -------------------- |
| `first`    | Go to first page.    |               |               |                      |
| `goto`     | Go to page at index. | `index`       | Number        | Index of the page.   |
| `last`     | Go to last page.     |               |               |                      |
| `next`     | Go to next page.     |               |               |                      |
| `previous` | Go to previous page. |               |               |                      |

### Custom Events

#### `change`

The event fired when the page changed.

The `change` event returns the following parameters.

| Parameter | Type   | Description               |
| --------- | ------ | ------------------------- |
| `value`   | string | The page number selected. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

### Styling Hooks

| CSS Variable                                                | Type    | Default   |
| ----------------------------------------------------------- | ------- | --------- |
| `--avonni-pagination-button-color-background`               | color   | `#fff`    |
| `--avonni-pagination-button-color-border`                   | color   | `#747474` |
| `--avonni-pagination-button-text-color`                     | color   | `#0176d3` |
| `--avonni-pagination-button-color-background-active`        | color   | `#f3f3f3` |
| `--avonni-pagination-button-color-border-active`            | color   | `#747474` |
| `--avonni-pagination-button-text-color-active`              | color   | `#014486` |
| `--avonni-pagination-button-color-background-hover`         | color   | `#f3f3f3` |
| `--avonni-pagination-button-color-border-hover`             | color   | `#747474` |
| `--avonni-pagination-button-text-color-hover`               | color   | `#014486` |
| `--avonni-pagination-button-color-background-disabled`      | color   | `#fff`    |
| `--avonni-pagination-button-color-border-disabled`          | color   | `#747474` |
| `--avonni-pagination-button-text-color-disabled`            | color   | `#c9c9c9` |
| `--avonni-pagination-active-button-color-background`        | color   | `#0176d3` |
| `--avonni-pagination-active-button-color-border`            | color   | `#0176d3` |
| `--avonni-pagination-active-button-text-color`              | color   | `#fff`    |
| `--avonni-pagination-active-button-color-background-active` | color   | `#014486` |
| `--avonni-pagination-active-button-color-border-active`     | color   | `#014486` |
| `--avonni-pagination-active-button-text-color-active`       | color   | `#fff`    |
| `--avonni-pagination-active-button-color-background-hover`  | color   | `#014486` |
| `--avonni-pagination-active-button-color-border-hover`      | color   | `#014486` |
| `--avonni-pagination-active-button-text-color-hover`        | color   | `#fff`    |
| `--avonni-pagination-button-sizing-border`                  | sizing  | `1px`     |
| `--avonni-pagination-button-styling-border`                 | styling | `solid`   |

## Key Considerations

* **The component holds no data:** It derives the page count from the total row count and the page size; fetching and slicing the records stays your component's job.
* **Page numbering starts at 1:** The current page is 1-based, and the default is the first page.
* **Minimum button count:** The maximum number of visible buttons is clamped to 3, so a smaller value has no effect.
* **Bookend buttons are opt-in:** The first and last buttons render only once you give them a label or an icon name.
* **Ellipsis behaviour:** The ellipsis appears only when there are more pages than visible buttons; its text is configurable, and it can be disabled on its own while the rest of the control stays interactive.
* **Best Practice:** Keep the page size in sync with the number of records your component actually renders, otherwise the page count will not match what the user sees.

***

## Troubleshooting Common Issues

* **Only one page button:** The page count comes from the total row count divided by the page size — confirm the total row count is set and greater than the page size.
* **Nothing happens on click:** The component reports the selected page but does not re-render your data; handle the `change` event and use its page number.
* **Ellipsis never appears:** It shows only when there are more pages than the visible button limit, and it stays hidden when the ellipsis is disabled.
* **Previous or next icon disappeared:** Setting a label on those buttons drops their default chevron; set the icon name explicitly to keep it.
* **If issues persist:** Contact our support team at <support@avonni.app> for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avonnicomponents.com/lwc-components/core-components/pagination.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.