Pagination

Ready

The Pagination component enables users to navigate through large sets of data by dividing content into discrete pages.

Storybook docs

Preview

Open in Storybook

Code

Install

npm install @fbin-web/neighborhood-core

Import

import { NbhdPagination } from '@fbin-web/neighborhood-core';

Usage

<nbhd-pagination
  current-page="2"
  total-pages="10"
  max-visible-pages="3"
  surface="secondary">
</nbhd-pagination>

Install

npm install @fbin-web/neighborhood-react

Import

import { NbhdPagination } from '@fbin-web/neighborhood-react';

Usage

import { NbhdPagination } from '@fbin-web/neighborhood-react';

const App = () => (
  <>
    <NbhdPagination
      currentPage={2}
      totalPages={10}
      maxVisiblePages={3}
      surface="secondary"></NbhdPagination>
  </>
);

Properties

Property	Attribute	Type	Default	Description
`surface`	`surface`	`noneprimarysecondaryinverseinverse-secondary`	`primary`	Surface to apply to the component
`marginTop`	`margin-top`	`nonesmallmediumlarge`	`none`	Top margin spacing.
`marginBottom`	`margin-bottom`	`nonesmallmediumlarge`	`none`	Bottom margin spacing.
`paddingTop`	`padding-top`	`defaultnonesmallmediumlarge`	`default`	Top padding spacing.
`paddingBottom`	`padding-bottom`	`defaultnonesmallmediumlarge`	`default`	Bottom padding spacing
`maxVisiblePages`	`max-visible-pages`	`number`	`3`	The maximum number of page buttons to display at once
`showLabels`	`show-labels`	`boolean`	`false`	Whether to show labels on the pagination arrows
`currentPage`	`current-page`	`number`	`1`	The current active page
`totalPages`	`total-pages`	`number`	`1`	The total number of pages
`nextLabel`	`next-label`	`string`	`Next`	The label for the next page arrow button
`previousLabel`	`previous-label`	`string`	`Previous`	The label for the previous page arrow button
`nextAriaLabel`	`next-aria-label`	`string`	—	Accessible name for the Next button. Defaults to "Next page", or to `next-label` when that has been changed so the name matches the visible text.
`previousAriaLabel`	`previous-aria-label`	`string`	—	Accessible name for the Previous button. Defaults to "Previous page", or to `previous-label` when that has been changed.
`label`	`label`	`string`	`Pagination`	Accessible name of the pagination navigation landmark.
`pageLabel`	`page-label`	`string`	`Page {page}`	Accessible name of each page button; `{page}` is replaced with the page number.
`onNbhdPageChanged`	`on-nbhd-page-changed`	`(event: CustomEvent<{ page: number }>) => void`	—	Callback function when page changes

Events

Name	Description	Event Detail
`nbhd-page-changed`	Emitted when the user navigates to a different page.	`{ page: number }`

CSS Parts

Exposed CSS parts for styling specific elements within the pagination component.

Name	Description
`page-button`	Individual page number buttons for navigation.
`ellipsis`	The ellipsis text elements ("...") shown between page ranges.
`base`	The main component wrapper element.
`nav`	The landmark wrapping the controls.
`controls`	The list of Previous, page and Next controls.
`previous-button`	The Previous button. Stays rendered on the first page with aria-disabled="true".
`pagination-item-svg`	The SVG arrow icons within the previous and next buttons.
`previous-label`	The text label for the previous button (when showLabels is true).
`next-button`	The Next button. Stays rendered on the last page with aria-disabled="true".
`next-label`	The text label for the next button (when showLabels is true).

nbhd-pagination::part(page-button) {
  /* your styles */
}

CSS Properties

Set these on nbhd-pagination or an ancestor to override the defaults. Token is the design token a default comes from and Value is what it resolves to in core Neighborhood; brands may override them. Properties that adapt to surface follow the light or inverse surface they sit on until you set them.

Pagination

Property	Token	Value
`--nbhd-pagination-controls-alignItems`	—	`center`
`--nbhd-pagination-controls-display`	—	`flex`
`--nbhd-pagination-controls-gap`	`--nbhd-space-2`	`8px`
`--nbhd-pagination-controls-justifyContent`	—	`center`
`--nbhd-pagination-controls-whiteSpace`	—	`nowrap`
`--nbhd-pagination-display`	—	`flex`
`--nbhd-pagination-ellipsis-fontSize`	`--nbhd-typography-subheading-fontSize`	`1.125rem`
`--nbhd-pagination-ellipsis-marginBlock`	`--nbhd-space-0`	`0px`
`--nbhd-pagination-inlineSize`	—	`100%`
`--nbhd-pagination-item-active-background-opacity`	—	`1`
`--nbhd-pagination-item-background-opacity`	—	`0`
`--nbhd-pagination-item-borderRadius`	`--nbhd-border-radius-md`	`6px`
`--nbhd-pagination-item-fontSize`	`--nbhd-typography-subheading-fontSize`	`1.125rem`
`--nbhd-pagination-item-hover-background-opacity`	—	`0.25`
`--nbhd-pagination-item-icon-display`	—	`inline-block`
`--nbhd-pagination-item-label-display`	—	`inline-block`
`--nbhd-pagination-item-label-fontSize`	`--nbhd-typography-body-fontSize`	`1rem`
`--nbhd-pagination-item-label-paddingInline`	`--nbhd-space-05`	`2px`
`--nbhd-pagination-item-minBlockSize`	`--nbhd-size-control-sm`	`28px`
`--nbhd-pagination-item-next-svg-transform`	—	`rotate(-90deg)`
`--nbhd-pagination-item-paddingBlock`	`--nbhd-space-1`	`4px`
`--nbhd-pagination-item-paddingInline`	`--nbhd-space-1`	`4px`
`--nbhd-pagination-item-previous-svg-transform`	—	`rotate(90deg)`
`--nbhd-pagination-item-svg-maxBlockSize`	—	`6px`
`--nbhd-pagination-item-svg-maxInlineSize`	`--nbhd-size-icon-xs`	`10px`
`--nbhd-pagination-item-svg-transform`	—	`none`
`--nbhd-pagination-justifyContent`	—	`center`
`--nbhd-pagination-marginInline`	—	`0`
`--nbhd-pagination-paddingBlock`	`--nbhd-space-1`	`4px`
`--nbhd-pagination-paddingInline`	—	`0`

Action plain

Property	Token	Value
`--nbhd-action-plain-backgroundColor`	`--nbhd-color-action-plain-background`	`rgba(0, 0, 0, 0)`
`--nbhd-action-plain-borderColor`	—	Override only
`--nbhd-action-plain-color`	`--nbhd-color-action-plain-foreground`	`#1b5e20`

Pagination item

Property	Token	Value	Copy
`--nbhd-paginationItem-active-color`	`--nbhd-context-color-action-primary-foreground`	Adapts to surface

Dependencies

Child components <nbhd-pagination> renders internally. Import them too when you tree-shake.

ButtonReady <nbhd-button> TextReady <nbhd-text>

Used by

Pagination SearchReady <nbhd-pagination-search>