Search documentation v0.6.1

Pagination

Display a list of links for divided content

Source ↗️ Report Issue ↗️

Use the Pagination component to display a list of links for different pages. Handle navigation on the client-side through JavaScript events, or use the Pagination component as a list of anchors. Supports different themes and types, such as dots or arrow paginations.

Preview
How to use Paginations in Astro
---
import { Pagination } from 'webcoreui/astro'
---
<Pagination />
<script>
import { listen } from 'webcoreui'
listen('paginate', event => {
console.log(event)
})
</script>
How to use Paginations in Svelte
<script>
import { Pagination } from 'webcoreui/svelte'
</script>
<Pagination onChange={event => console.log(event)} />
How to use Paginations in React
import React from 'react'
import { Pagination } from 'webcoreui/react'
const Component = () => (
<Pagination onChange={event => console.log(event)} />
)
export default Component

The Pagination component can be created without any props. In this case, pagination starts at page 1, and goes on indefinitely. To listen to page change events, you can listen to the paginate event in Astro, or use the onChange prop for Svelte/React components. The event object returns the following properties:

Event object
{
page: 1 // The current page
direction: 'prev' // The direction, either 'prev' or 'next'
label: 'Page 1', // If available, the label of the current page
}

Customize Previous/Next

The Previous/Next buttons can be customized using the following props:

Default
With chevrons
With chevrons & labels
<Pagination
showChevrons={true}
previousPageLabel="Back"
nextPageLabel="Forward"
/>

Previous/Next States

The states of the Previous/Next buttons can also be configured using the following additional props:

<Pagination
previousLink="#"
disableNext={true}
/>

If a link is set for the Previous/Next buttons, the button element is replaced with an anchor and the button will behave as a link. If conflicting props are present and the button has a link while disabled, the element will be rendered as a disabled button.

Page States

Page states can also be set explicitly using the totalPages and currentPage props. For example, the following pagination has 5 pages, with the current page set to 2:

Click on the Next button 3 times to navigate to the last page
<Pagination
currentPage={2}
totalPages={5}
/>

When the user reaches the last page, the Next button will automatically gets disabled. Likewise, if the user reaches the first page, the Previous button gets disabled.

Pages

When dealing with multiple pages as in the above example, it’s visually not indicated to the user which page they’re currently on. To show page numbers, we can use the pages prop that expects an array of objects in the following format:

<Pagination
pages={[
{ label: 1 },
{ label: 2 },
{ label: 3, active: true },
{ label: 4 },
{ label: 5 }
]}
/>
Using the currentPage and totalPages props will override the default behavior of the pages prop.

If you’d like to indicate to the user that there are an arbitrary number of pages that are currently not displayed, you can set the showDots prop to true to display ”…” after the last page:

<Pagination
showDots={true}
pages={[
{ label: 1 },
{ label: 2 },
{ label: 3, active: true },
{ label: 4 },
{ label: 5 }
]}
/>

Themes

As the Pagination component is made of Button components, it supports the use of button themes. See the API documentation of the Button component to see all available themes.

Primary
Secondary
Flat
<Pagination theme="primary" />
<Pagination theme="secondary" />
<Pagination theme="flat" />

Types

The Pagination component also comes with two different built-in types, arrows and dots:

Arrows
Dots
<Pagination type="arrows" />
<Pagination type="dots" totalPages={3} />

By the nature of the dots type pagination, you must provide either the totalPages or pages prop along with the type to render the component.

API

type PaginationEventType = {
page: number
direction: 'prev' | 'next'
label?: string | number
}
type PaginationProps = {
type?: 'arrows' | 'dots'
showChevrons?: boolean
showDots?: boolean
disablePrevious?: boolean
disableNext?: boolean
previousLink?: string
nextLink?: string
previousPageLabel?: string
nextPageLabel?: string
className?: string
theme?: ButtonProps['theme']
totalPages?: number
currentPage?: number
pages?: {
label: number | string
active?: boolean
link?: string
}[]
}
type SveltePaginationProps = {
onChange?: (event: PaginationEventType) => void
} & PaginationProps
type ReactPaginationProps = {
onChange?: (event: PaginationEventType) => void
} & PaginationProps
See the documentation of the Button component for the ButtonProps['theme'] type for the theme prop.
PropDefaultPurpose
type null Sets the type of the Pagination component. Can be one of arrows, dots, or null.
showChevrons false Show chevron icons for previous and next buttons.
showDots false Shows dots between previous and next buttons to indicate more pages.
disablePrevious false Disables the previous button.
disableNext false Disables the next button.
previousLink - Sets a link for the previous button.
nextLink - Sets a link for the next button.
previousPageLabel Previous Sets the label of the previous button.
nextPageLabel Previous Sets the label of the next button.
theme outline Sets the theme of the pagination. Can be one of the button themes.
totalPages - Sets the total number of pages explicitly. Use for cases where you don't want to use the pages prop, or you need to override default behavior.
currentPage - Sets the currently active page. Use for cases where you don't want to use the pages prop, or you need to override default behavior.
className - Pass additional CSS classes for the pagination.
pages - Sets a arbitrary number of page links between the previous and next buttons.
pages.label - Sets a label for the page link.
pages.active - Sets a page link as active.
pages.link - Sets a link for the page link. Omit if you want to handle navigation in JavaScript.
Svelte & React PropPurpose
onChange Attach on-change event listeners.

Request improvement for this page