# @asphalt-react/pagination

> Pagination

Latest version **2.16.0** (published 2026-07-28) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install @asphalt-react/pagination
pnpm add @asphalt-react/pagination
yarn add @asphalt-react/pagination
bun add @asphalt-react/pagination
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 2.16.0 |
| Published | 2026-07-28 |
| First published | 2022-03-30 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 6 |
| Unpacked size | 81.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | UX Engineering - Web |
| Maintainers | sayantan1211, dawn29, antoniomontana, goto.abhinav, elayudhanira-gojek, yessyprmtsr, soorajj |
| Keywords | asphalt, pagination, component, dls, design language system |

## Links

- npm: https://www.npmjs.com/package/@asphalt-react/pagination
- npm.io page: https://npm.io/package/@asphalt-react/pagination

## Dependencies (6)

- [classnames](https://npm.io/package/classnames.md) ^2.5.1
- [prop-types](https://npm.io/package/prop-types.md) ^15.8.1
- [@asphalt-react/button](https://npm.io/package/@asphalt-react/button.md) ^2.16.0
- [@asphalt-react/helper](https://npm.io/package/@asphalt-react/helper.md) ^2.16.0
- [@asphalt-react/iconpack](https://npm.io/package/@asphalt-react/iconpack.md) ^2.16.0
- [@asphalt-react/toggle-button](https://npm.io/package/@asphalt-react/toggle-button.md) ^2.16.0

## Recent versions

- 2.16.0 (latest) — 2026-07-28
- 2.0.0-alpha.29 (next) — 2023-12-15
- 2.15.1 — 2026-04-28
- 2.15.0 — 2026-04-13
- 2.14.0 — 2026-03-11
- 2.13.0 — 2026-02-19
- 2.12.2 — 2026-01-28
- 2.12.1 — 2025-12-19
- 2.12.0 — 2025-11-28
- 2.11.0 — 2025-11-10
- 2.10.0 — 2025-10-27
- 2.9.0 — 2025-10-02
- 2.8.1 — 2025-09-10
- 2.8.0 — 2025-08-14
- 2.6.0 — 2025-07-11
- … 29 more at https://npm.io/package/@asphalt-react/pagination/versions

## README

# Pagination

![npm](https://img.shields.io/npm/dt/@asphalt-react/pagination?style=flat-square)
[![npm version](https://badge.fury.io/js/@asphalt-react%2Fpagination.svg)](https://badge.fury.io/js/@asphalt-react%2Fpagination)

Pagination component divides content into discrete pages. Use this component to show long lists of data divided across pages for a better experience. Pagination contains a list of links or buttons called page tiles to navigate through the pages. You can control the number of page tiles visible. Pagination also allows users to navigate to next, previous, first and last pages through actionable elements called steppers. They are visible by default, but you can choose to hide them.

Pagination components exports PerPage component. You can use this to set the number of records visible on each page.

You can also create a custom Pagination through a family of unit components and hooks exported by Pagination and other Asphalt React components.

## Usage

```jsx
import React, { useState } from "react"
import { Link } from "gatsby" // or any other router like react-router
import { Pagination, PerPage } from "@asphalt-react/pagination"

function App() {
  const [active, setActive] = useState(1)
  const [current, setCurrent] = useState(10)

  const getTileProps = (num) => ({
    to: `?page=${num}`,
  })

  const getPerPageTileProps = (recordsPerPage) => ({
    to: `?perPage=${recordsPerPage}`,
  })

  const handlePageChange = (e, pageNum) => {
    setActive(pageNum)
  }

  const handlePerPageChange = (e, records) => {
    setCurrent(records)
  }

  return (
    <div >
      <Pagination
        totalPages={50}
        as={Link}
        getTileProps={getTileProps}
        active={active}
        onChange={handlePageChange}
        slim
      />
      <div>
        <div>Items/Page: </div>
        <PerPage
          as={Link}
          getTileProps={getPerPageTileProps}
          recordsPerPage={[10, 25, 50, 100]}
          active={current}
          onChange={handlePerPageChange} 
        />
      </div>
    </div>
  )
}
```

## Variants

Pagination has 3 variants to configure the number of page tiles:

1. `minimal` - contains only active page tile.
2. `slim` - contains 3 page tiles including active page tile. This is the default variant.
3. `extended` - contains 5 page tiles including active page tile.

## Accessibility

* Use <kbd>tab</kbd> or <kbd>shift+tab</kbd> to navigate among pages.

## Creating a custom Pagination

Pagination exports layout unit components and hooks using which you can create a custom implementation.

### Components

1. BasePagination
2. PageItem

### Hooks

#### usePagination

React hook to implement the functionality of Pagination in your custom implementation. You can customize the tile count and add truncation to your component. Truncation is a visual aid to let users know that some page tiles are hidden behind the truncation symbol like an ellipses.

```jsx
import { BasePagination, usePagination } from "@asphalt-react/pagination"
import { ToggleButton } from "@asphalt-react/toggle-button"
import { ToggleButton } from "@asphalt-react/button"
import {
	ChevronBackward,
	ChevronForward,
	ChevronLeft,
	ChevronRight,
	More
} from "@asphalt-react/iconpack"

export const Pagination = () => {
	const { getPagesList } = usePagination({
    active,
    totalPages,
    tileCount: 5,
  })

	const pages = getPagesList({ truncate: false })

	return (
		<BasePagination>
      <PageItem>
        <Button
          link={false}
          disabled={!link && active === 1}
          nude
          icon
          compact
          system
          onClick={(e) => onChange(e, 1)}
        >
          <ChevronBackward />
        </Button>
      </PageItem>
      <PageItem>
        <Button
          link={false}
          disabled={!link && active === 1}
          nude
          icon
          compact
          system
          onClick={(e) => onChange(e, active - 1)}
        >
          <ChevronLeft />
        </Button>
      </PageItem>

      {pages.map((pageNum) =>
        <PageItem key={`page-${pageNum}`}>
          <ToggleButton
            link={false}
            seamless
            compact
            underline={false}
            onClick={(e) => onChange(e, pageNum)}
            on={pageNum === active}
          >
            {pageNum}
          </ToggleButton>
        </PageItem>
      )}

      <PageItem>
        <Button
          link={false}
          disabled={!link && active === totalPages}
          nude
          icon
          compact
          system
          onClick={(e) => onChange(e, active + 1)}
        >
          <ChevronRight />
        </Button>
      </PageItem>

      <PageItem>
        <Button
          link={false}
          disabled={!link && active === totalPages}
          nude
          icon
          compact
          system
          onClick={(e) => onChange(e, totalPages)}
        >
          <ChevronForward />
        </Button>
      </PageItem>
    </BasePagination>
	)
}
```

1. `usePagination` accepts the following props:
   * `active` - active page number.
   * `totalPages` - total number of pages.
   * `tileCount` - page tile count.
2. It returns functions which exposes certain functionality of pagination.
   * `isStartTruncated()` - returns a boolean value denoting truncation at start of page tiles
   * `isEndTruncated` - returns a boolean value denoting truncation at end of page tiles
   * `getPagesList({ truncate = false })` - returns an array of page numbers which can be used to render the page tiles of pagination. Accepts truncate as a boolean argument.
   * The output of `getPagesList` contains `-1`, specifying the position of truncation.

[comment]: # "Pagination Props"

## Props

### totalPages

Total number of available pages.

| type   | required | default |
| ------ | -------- | ------- |
| number | true     | N/A     |

### active

Current page number.

| type   | required | default |
| ------ | -------- | ------- |
| number | false    | 1       |

### onChange

Callback to be called when page changes.

onChange receives an object with the following shape.

* event - browser event
* page - active page number

```
({ event, page }) => {}
```

| type | required | default |
| ---- | -------- | ------- |
| func | false    | N/A     |

### as

Html element/React component to replace the default element. Using this prop, you can use your router's link element, such as "react-router-dom"'s Link element.

| type        | required | default |
| ----------- | -------- | ------- |
| elementType | false    | "a"     |

### getTileProps

Function to generate props such as "href", "id", data-attributes etc. for page tiles.

| type | required | default |
| ---- | -------- | ------- |
| func | false    | N/A     |

### link

Render a link.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

### stepper

Toggle visibility for next and previous stepper.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

### previousStepperProps

Function to generate props such as "href", "id", data-attributes etc. for the previous stepper element.

| type | required | default |
| ---- | -------- | ------- |
| func | false    | N/A     |

### nextStepperProps

Function to generate props such as "href", "id", data-attributes etc. for the next stepper element.

| type | required | default |
| ---- | -------- | ------- |
| func | false    | N/A     |

### edgeStepper

Toggle visibility for left and right edge stepper.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

### leftEdgeStepperProps

Function to generate props such as "href", "id", data-attributes etc. for the left edge stepper element.

| type | required | default |
| ---- | -------- | ------- |
| func | false    | N/A     |

### rightEdgeStepperProps

Function to generate props such as "href", "id", data-attributes etc. for the right edge stepper element.

| type | required | default |
| ---- | -------- | ------- |
| func | false    | N/A     |

### minimal

Variant to show current active tile, stepper and edge stepper.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### slim

Variant to show 3 page tiles, stepper and edge stepper.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### extended

Variant to show 5 page tiles, stepper and edge stepper.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### nextStepperLabel

aria-label for next stepper.

| type   | required | default           |
| ------ | -------- | ----------------- |
| string | false    | "go to next page" |

### previousStepperLabel

aria-label for previous stepper.

| type   | required | default               |
| ------ | -------- | --------------------- |
| string | false    | "go to previous page" |

### leftEdgeStepperLabel

aria-label for left edge stepper.

| type   | required | default            |
| ------ | -------- | ------------------ |
| string | false    | "go to first page" |

### rightEdgeStepperLabel

aria-label for right edge stepper.

| type   | required | default           |
| ------ | -------- | ----------------- |
| string | false    | "go to last page" |

# PerPage

Set number of records visible on each page.

[comment]: # "PerPage Props"

## Props

### recordsPerPage

Array of numbers representing PerPage indices.

| type    | required | default           |
| ------- | -------- | ----------------- |
| arrayOf | false    | [10, 25, 50, 100] |

### as

Html element/React component to replace the default element. Using this prop, you can use your router's link element, such as "react-router-dom"'s Link element.

| type        | required | default |
| ----------- | -------- | ------- |
| elementType | false    | "a"     |

### active

Number of records per page

| type   | required | default |
| ------ | -------- | ------- |
| number | false    | 10      |

### getTileProps

Function to generate props such as "href", "id" for the custom link element passed in `as` prop.

| type | required | default |
| ---- | -------- | ------- |
| func | false    | N/A     |

### onChange

Function to be called when per page value changes

onChange receives an object with the following signature

* event - click event
* records - number of records to show per page

```
 ({event, record}) => void
```

| type | required | default |
| ---- | -------- | ------- |
| func | false    | N/A     |

### link

Render a link

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

# BasePagination

The base container unit component.

[comment]: # "BasePagination Props"

## Props

### children

Container for the BasePagination content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | N/A     |

### gap

Adds gap between child elements

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

# PageItem

Renders the list element for page tiles.

[comment]: # "PageItem Props"

## Props

### children

Content for a page list item.

| type | required | default |
| ---- | -------- | ------- |
| node | true     | N/A     |

---
_Source: https://npm.io/package/@asphalt-react/pagination · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._