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.
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:
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.
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.
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:
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.
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:
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.
Types
The Pagination
component also comes with two different built-in types, arrows
and dots
:
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
Prop | Default | Purpose |
---|---|---|
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 Prop | Purpose |
---|---|
onChange | Attach on-change event listeners. |
Request improvement for this page