Pagination

Display a list of links for divided content

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.

---
import { Pagination } from 'webcoreui/astro'
---

<Pagination />

<script>
    import { listen } from 'webcoreui'

    listen('paginate', event => {
        console.log(event)
    })
</script>

<script>
    import { Pagination } from 'webcoreui/svelte'
</script>

<Pagination onChange={event => console.log(event)} />

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:

{
    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:

• showChevrons: Show chevron icons next to the previous/next labels.
• previousPageLabel: Sets the Previous button label.
• nextPageLabel: Sets the Next button label.

<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:

• disablePrevious: Disables the Previous button.
• disableNext: Disables the Next button.
• previousLink: Sets a link for the Previous button.
• nextLink: Sets a link for the Next button.

<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:

<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:

• label: Sets a label for the page. Can be numbers or strings.
• active: Sets the button as active.
• link: Sets a link for the button to behave as an anchor.

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

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.

<Pagination theme="primary" />
<Pagination theme="secondary" />
<Pagination theme="flat" />

Types

The Pagination component also comes with two different built-in types, arrows and 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