Skip to main content
Neighborhood Design System v5.1.0

Pagination Search

Ready

A pagination component with additional search sorting functionality.

Storybook docs (opens in new tab)

Preview

Open in Storybook (opens in new tab)

Code

Install
npm install @fbin-web/neighborhood-core
Import
import { NbhdPaginationSearch } from '@fbin-web/neighborhood-core';
Usage
<nbhd-pagination-search
  selected-sort="relevance"
  heading="Search Results for"
  search-term="faucet"
  current-page="1"
  total-pages="10"
  total-results="75"
  max-visible-pages="3"
  surface="secondary">
</nbhd-pagination-search>

<script>
  const paginationSearch = document.querySelector('nbhd-pagination-search');

  paginationSearch.sortOptions = [
    { name: 'Relevance', value: 'relevance' },
    { name: 'Price: Low to High', value: 'price-asc' },
    { name: 'Price: High to Low', value: 'price-desc' },
    { name: 'Newest', value: 'newest' },
  ];
</script>

Usage

  • Pagination Search extends the Pagination component by adding search and sorting functionality.

Properties

PropertyAttributeTypeDefaultDescription
surfacesurfacenoneprimarysecondaryinverseinverse-secondaryprimarySurface to apply to the component.
marginTopmargin-topnonesmallmediumlargenoneTop margin spacing.
marginBottommargin-bottomnonesmallmediumlargenoneBottom margin spacing.
paddingToppadding-topdefaultnonesmallmediumlargedefaultTop padding spacing.
paddingBottompadding-bottomdefaultnonesmallmediumlargedefaultBottom padding spacing.
maxVisiblePagesmax-visible-pagesnumber3The maximum number of page buttons to display at once.
showLabelsshow-labelsbooleanfalseWhether to show labels on the pagination arrows.
currentPagecurrent-pagenumber1The current active page.
totalPagestotal-pagesnumber1The total number of pages.
nextLabelnext-labelstringNextThe label for the next page arrow button.
previousLabelprevious-labelstringPreviousThe label for the previous page arrow button.
labellabelstringPaginationAccessible name of the pagination navigation landmark.
onNbhdPageChangedon-nbhd-page-changed(event: CustomEvent<{ page: number }>) => void—Callback function when page changes.
headingheadingstringSearch Results forText displayed before the search term in the results summary.
headingLevelheading-level1234562Level of the results summary heading ("Search Results for “term” [N]"). Match it to the page outline.
resultsAnnouncementresults-announcementstring{count} resultsAnnounced to screen readers when the result count or search term changes (not on first load). `{count}` is replaced with `total-results`.
searchTermsearch-termstring—The current search term to display alongside the results summary.
totalResultstotal-resultsnumber0The total number of search results.
selectedSortselected-sortstringrelevanceThe currently selected sort option.
sortLabelsort-labelstringSort By: The label shown before the sort select dropdown.
onNbhdSortChangedon-nbhd-sort-changed(event: CustomEvent<{ value: string }>) => void—Callback function when the sort option changes.
sortOptions—SelectOptionContent[][]An array of sort options for the select dropdown.

Select Option Content Structure

Each item in sortOptions must match the SelectOptionContent shape used by the shared select component.

PropertyTypeRequiredDescription
namestringYesDisplay label shown for the sort option in the dropdown.
valuestringYesValue assigned to the option and used when the selection changes.

Events

NameDescriptionEvent Detail
nbhd-page-changedEmitted when the user navigates to a different page.{ page: number }
nbhd-sort-changedEmitted when the sort option changes.{ value: string }

CSS Parts

Parts exposed for styling the pagination-search component.

NameDescription
baseThe component's outer wrapper.
containerThe internal container that wraps the search summary and controls.
wrapperThe content wrapper containing the summary, pagination, and sort controls.
summaryThe results summary row showing the heading, term, and result count.
summary-headingThe heading text before the search term.
summary-termThe active search term shown in the summary.
summary-resultsThe results count displayed in the summary.
paginationThe pagination section wrapper.
navThe
controlsThe
    list of Previous, page and Next controls.
page-buttonEach page number button in the pagination set.
previous-buttonThe Previous button. Stays rendered on the first page with aria-disabled="true".
next-buttonThe Next button. Stays rendered on the last page with aria-disabled="true".
previous-labelThe label text for the previous button when labels are visible.
next-labelThe label text for the next button when labels are visible.
ellipsisThe ellipsis indicators between pagination groups.
pagination-item-svgThe SVG icon rendered inside the previous and next buttons.
sortThe sort row wrapper containing the dropdown and label.
sort-labelThe label text before the sort select control.
sort-selectThe select control used for sorting options.
nbhd-pagination-search::part(base) {
  /* your styles */
}

CSS Properties

Set these on nbhd-pagination-search 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.

PropertyTokenValue Copy
--nbhd-paginationSearch-inlineSize—100%
--nbhd-paginationSearch-minInlineSize--nbhd-size-container-min320px
--nbhd-paginationSearch-paddingBlock--nbhd-space-520px
--nbhd-paginationSearch-position—relative
--nbhd-paginationSearch-sort-alignItems—center
--nbhd-paginationSearch-sort-display—flex
--nbhd-paginationSearch-sort-gap--nbhd-space-28px
--nbhd-paginationSearch-sort-justifyContent—center
--nbhd-paginationSearch-sort-select-inlineSize—165px
--nbhd-paginationSearch-sort-text-display—inline
--nbhd-paginationSearch-sort-text-hostDisplay—inline-block
--nbhd-paginationSearch-summary-alignItems—center
--nbhd-paginationSearch-summary-display—flex
--nbhd-paginationSearch-summary-gap--nbhd-space-14px
--nbhd-paginationSearch-summary-justifyContent—center
--nbhd-paginationSearch-summary-maxInlineSize—content
--nbhd-paginationSearch-summary-text-display—inline
--nbhd-paginationSearch-summary-text-hostDisplay—inline-block
--nbhd-paginationSearch-wrapper-alignItems—center
--nbhd-paginationSearch-wrapper-bpMd-flexDirection—row
--nbhd-paginationSearch-wrapper-display—flex
--nbhd-paginationSearch-wrapper-flexDirection—column
--nbhd-paginationSearch-wrapper-flexWrap—wrap
--nbhd-paginationSearch-wrapper-gap--nbhd-space-520px
--nbhd-paginationSearch-wrapper-inlineSize—100%
--nbhd-paginationSearch-wrapper-justifyContent—space-between
--nbhd-paginationSearch-zIndex--nbhd-z-11

Dependencies

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

Esc
↑ ↓ to move↵ to open