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.

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

// 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.

<!-- 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 [email protected] for assistance.