Pagination
<ahi-pagination> | AhiPagination
Cursor-based pagination component that allows navigation through pages of data when the total count is unknown.
Pagination allows users to navigate through large datasets by breaking them into smaller, manageable pages. This cursor-based implementation is ideal when the total number of items is unknown.
<ahi-pagination
page-size="25"
current-page="3">
</ahi-pagination>
Examples
Basic Usage
The pagination component requires page-size and current-page properties. Use
no-previous and no-next to disable navigation buttons when needed.
<ahi-pagination
page-size="10"
current-page="1"
no-previous>
</ahi-pagination>
Page Size Options
Customize available page sizes using the page-sizes attribute. The default options are
[10, 25, 50, 100].
<ahi-pagination
page-size="20"
page-sizes="[5, 10, 20, 50]"
current-page="2">
</ahi-pagination>
Navigation States
Control the availability of previous and next navigation using the no- prefixed boolean
properties.
<!-- First page - no previous -->
<ahi-pagination
page-size="25"
current-page="1"
no-previous>
</ahi-pagination>
<br>
<!-- Middle page - both available -->
<ahi-pagination
page-size="25"
current-page="5">
</ahi-pagination>
<br>
<!-- Last page - no next -->
<ahi-pagination
page-size="25"
current-page="10"
no-next>
</ahi-pagination>
Disabled States
Use no-previous and no-next to disable navigation buttons when needed (e.g.,
during loading or when no more data is available).
<ahi-pagination
page-size="25"
current-page="3"
no-previous>
</ahi-pagination>
Cursor-Based Pagination
The component supports cursor-based pagination for datasets where the total count is unknown. Pass the cursor value for tracking position.
<ahi-pagination
page-size="50"
current-page="2"
cursor="eyJpZCI6MTIzfQ==">
</ahi-pagination>
Events
Listen for navigation and page size change events to handle data fetching.
<ahi-pagination
id="event-example"
page-size="25"
current-page="1"
no-previous>
</ahi-pagination>
<div id="event-log" style="margin-top: 1rem; padding: 1rem; background: var(--ahi-surface-neutral-subdued); border-radius: 0.375rem; font-family: monospace; font-size: 0.875rem; max-height: 150px; overflow-y: auto;"></div>
<script>
const pagination = document.getElementById('event-example');
const eventLog = document.getElementById('event-log');
function logEvent(message) {
const entry = document.createElement('div');
entry.textContent = `${new Date().toLocaleTimeString()}: ${message}`;
eventLog.appendChild(entry);
eventLog.scrollTop = eventLog.scrollHeight;
}
pagination.addEventListener('ahi-pagination-navigate', (event) => {
const { direction, pageSize, currentCursor } = event.detail;
logEvent(`Navigation: ${direction}, Page Size: ${pageSize}`);
});
pagination.addEventListener('ahi-pagination-page-size-change', (event) => {
const { pageSize, currentCursor } = event.detail;
logEvent(`Page size changed: ${pageSize}`);
});
logEvent('Event listeners initialized');
</script>
Usage Guidelines
When to Use
- Large datasets where showing all items would impact performance
- Search results with many pages of content
- Data tables with configurable page sizes
- API integrations using cursor-based pagination
Best Practices
- Always provide clear feedback about the current page and range
- Use reasonable default page sizes (25–50 items)
- Provide loading states during navigation
- Remember the user’s page size preference
Importing
To import this component using a script tag:
<script type="module" src="/path/to/azalea-kit-ui/dist/components/pagination/pagination.js"></script>To import this component using a bundler:
import '@azaleahealth/azalea-kit-ui/dist/components/pagination/pagination.js';Properties
| Name | Description | Type | Default | |
|---|---|---|---|---|
pageSizes
page-sizes
|
Available page size options for the dropdown. Determines which values appear in the page size selector dropdown. |
number[]
|
[10, 25, 50, 100]
|
|
pageSize
page-size
|
The current page size. Controls how many items are displayed per page. |
number
|
25
|
|
cursor
|
The current cursor position for cursor-based pagination. Used to track the current position in the dataset when total count is unknown. |
string | undefined
|
- | |
currentPage
current-page
|
The current page number (1-based index). Used for display purposes in the range label calculation. |
number
|
1
|
|
noPrevious
no-previous
|
Disables the previous button. Set to true when there is no previous page available or when you want to manually disable the button. |
boolean
|
false
|
|
noNext
no-next
|
Disables the next button. Set to true when there is no next page available or when you want to manually disable the button. |
boolean
|
false
|
|
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about properties and attributes.
Events
| Name | Description | Event Detail |
|---|---|---|
ahi-pagination-navigate |
Emitted when previous/next buttons are clicked |
{ direction: 'previous' | 'next', pageSize: number, currentCursor?: string }
|
ahi-pagination-page-size-change |
Emitted when page size is changed |
{ pageSize: number, currentCursor?: string }
|
Learn more about events.
CSS Parts
| Name | Description |
|---|---|
base |
Deprecated. Use the pagination part instead. |
pagination |
The component’s outer wrapper. |
left-section |
The left section containing the page size selector. |
page-size-selector |
The page size selector container. |
page-size-label |
The “Items per page” label. |
page-size-select |
The page size dropdown select element. |
range-label |
The range label showing current visible items. |
right-section |
The right section containing navigation buttons. |
navigation-buttons |
The navigation buttons container. |
nav-button |
The base navigation button styling. |
prev-button |
The previous page button. |
next-button |
The next page button. |
Learn more about customizing CSS parts.