Skip to main content
Neighborhood Design System v5.1.0

Filters

Ready

Filters component provides a user-friendly interface for refining search or data results.

Preview

Open in Storybook (opens in new tab)

Code

Install
npm install @fbin-web/neighborhood-core
Import
import { NbhdFilters } from '@fbin-web/neighborhood-core';
Usage
<nbhd-filters total-results="10"> </nbhd-filters>

<script>
  const filters = document.querySelector('nbhd-filters');

  filters.filters = [
    {
      title: 'Category',
      key: 'category',
      expanded: false,
      description: 'Integer posuere erat a ante venenatis dapibus posuere velit aliquet.',
      options: [
        {
          label: 'Kitchen',
          count: 420,
          value: 'Kitchen',
          selected: false,
        },
        {
          label: 'Kitchen Faucets',
          count: 418,
          value: 'Kitchen Faucets',
          selected: false,
        },
        {
          label: 'Kitchen Sink Faucets',
          count: 416,
          value: 'Kitchen Sink Faucets',
          selected: false,
        },
        {
          label: 'Smart Home',
          count: 22,
          value: 'Smart Home',
          selected: false,
        },
        {
          label: 'Kitchen Accessories',
          count: 2,
          value: 'Kitchen Accessories',
          selected: false,
        },
        {
          label: 'Dispensers',
          count: 2,
          value: 'Dispensers',
          selected: false,
        },
        {
          label: 'Parts',
          count: 2,
          value: 'Parts',
          selected: true,
        },
      ],
    },
    {
      title: 'Collection',
      key: 'Collection',
      expanded: false,
      options: [
        {
          label: 'Align',
          count: 10,
          value: 'Align',
          selected: false,
        },
        {
          label: 'Sleek',
          count: 8,
          value: 'Sleek',
          selected: false,
        },
        {
          label: 'Chateau',
          count: 31,
          value: 'Chateau',
          selected: false,
        },
        {
          label: 'Adler',
          count: 19,
          value: 'Adler',
          selected: false,
        },
        {
          label: 'Camerist',
          count: 17,
          value: 'Camerist',
          selected: false,
        },
      ],
    },
    {
      title: 'Finish',
      key: 'Finish',
      tooltip: 'Select your favorite colors',
      expanded: false,
      options: [
        {
          label: 'Chrome',
          count: 288,
          value: 'chrome',
          selected: false,
          finishImage: 'https://moen.widen.net/content/3d7ihxrfrz/png/chrome_100.png',
        },
        {
          label: 'Spot Resist Stainless',
          count: 261,
          value: 'spot resist stainless',
          selected: true,
          finishImage: 'https://moen.widen.net/content/3d7ihxrfrz/png/chrome_100.png',
        },
        {
          label: 'Matte Black',
          count: 129,
          value: 'matte black',
          selected: true,
        },
        {
          label: 'Classic Stainless',
          count: 58,
          value: 'classic stainless',
          selected: false,
        },
        {
          label: 'Oil Rubbed Bronze',
          count: 55,
          value: 'oil rubbed bronze',
          selected: false,
        },
        {
          label: 'Brushed Gold',
          count: 36,
          value: 'brushed gold',
          selected: false,
        },
        {
          label: 'Stainless',
          count: 32,
          value: 'stainless',
          selected: false,
        },
        {
          label: 'Bronzed Gold',
          count: 31,
          value: 'bronzed gold',
          selected: false,
        },
        {
          label: 'Mediterranean Bronze',
          count: 30,
          value: 'mediterranean bronze',
          selected: false,
        },
        {
          label: 'Polished Nickel',
          count: 28,
          value: 'polished nickel',
          selected: false,
        },
      ],
    },
    {
      title: 'Type Of Handles',
      key: 'Type of Handles',
      expanded: false,
      options: [
        {
          label: 'Lever Handles',
          count: 404,
          value: 'Lever handles',
          selected: false,
          tooltip:
            'Nulla vitae elit libero, a pharetra augue. Etiam porta sem malesuada magna mollis euismod.',
        },
        {
          label: 'Knob Handles',
          count: 10,
          value: 'Knob handles',
          selected: false,
        },
        {
          label: 'Lever And Knob Handles',
          count: 2,
          value: 'Lever and knob handles',
          selected: false,
        },
        {
          label: 'Lever And Cross Handles',
          count: 1,
          value: 'Lever and cross handles',
          selected: false,
        },
      ],
    },
    {
      title: '',
      key: 'facets-1',
      options: [{ label: 'Option 1' }, { label: 'Option 2' }, { label: 'Option 3' }],
    },
  ];
</script>

Properties

PropertyAttributeTypeDefaultDescription
filters—FilterGroup[][]Array of filter groups and their options. This property is not settable via attribute.
surfacesurfacenoneprimarysecondaryinverseinverse-secondaryprimarySurface color for the component.
headingheadingstringFiltersHeading displayed for the filters component.
headingLevelheading-level1234564Level of the "Filters" heading. Match it to the page outline.
clearFiltersLabelclear-filters-labelstringRemove allLabel for the button that clears all selected filters.
maxVisibleOptionsmax-visible-optionsnumber3Maximum number of filter options displayed before the expand button is shown.
expandLabelexpand-labelstringShow moreLabel for the button that displays additional filter options.
collapseLabelcollapse-labelstringShow lessLabel for the button that hides additional filter options.
totalResultstotal-resultsnumber0Total number of results used to determine whether a filter group should be visually hidden.
countStylecount-styleroundsquarecurlysquareBracket style used to display filter option counts.
removeFilterLabelremove-filter-labelstringRemove filterPrefix for each selected-filter chip’s accessible name, e.g. "Remove filter: Chrome".
resultsAnnouncementresults-announcementstring{count} resultsAnnounced to screen readers after a filter change once `total-results` updates. `{count}` is replaced with the result count.
drawerLabeldrawer-labelstringResults filter optionsAccessible name of the mobile filters drawer.
resetLabelreset-labelstringResetText of the drawer's Reset button.
resetAriaLabelreset-aria-labelstring—Accessible name for the Reset button. Defaults to "Reset Filters", or to `reset-label` when that has been changed so the name matches the visible text.
doneLabeldone-labelstringDoneText of the drawer's Done button.
doneAriaLabeldone-aria-labelstring—Accessible name for the Done button. Defaults to "Done, close filters", or to `done-label` when that has been changed.
closeLabelclose-labelstringClose filtersAccessible name of the drawer's close button.

Filter Group Structure

Structure for FilterGroup objects used in the filters property.

PropertyTypeRequiredDescription
keystringYesUnique identifier for the filter group.
titlestringNoDisplay title for the filter group.
descriptionstringNoPlain text shown under the filter group's options. HTML is shown as text, not rendered.
expandedbooleanNoWhether the filter group is expanded by default.
tooltipstringNoTooltip text to display for the filter group.
optionsFilterOption[]NoArray of filter options within this group.

Filter Option Structure

Structure for FilterOption objects used within the FilterGroup options property.

PropertyTypeRequiredDescription
labelstringYesDisplay label for the filter option.
countnumberNoNumber of results for this filter option.
tooltipstringNoTooltip text for the filter option.
selectedbooleanNoWhether the filter option is currently selected.
hrefstringNoURL associated with the filter option.
valuestringNoValue associated with the filter option.
finishImagestringNoImage URL for finish-related filter options.

Events

NameDescriptionEvent Detail
nbhd-filter-changeEmitted when filter selections change.{ selectedFilters: FilterOptionEmitted[] }

CSS Parts

NameDescription
baseThe root filters component container.
sidebarThe desktop sidebar container.
sidebar-filter-groupsThe filter groups container in the desktop sidebar.
drawerThe mobile filter drawer container.
headerThe filters header containing the heading and clear action.
headingThe filters heading text element.
selected-filtersThe container for selected filter buttons.
selected-filterAn individual selected filter button.
filter-group-toggleThe button that expands or collapses a filter group.
filter-group-panelThe expandable panel containing a filter group's options.
checkboxAn individual filter option checkbox.
imageThe finish image wrapper for filter options with finish images.
tooltipThe filter tooltip container.
tooltip-descriptionThe filter tooltip description text.
sidebar-clearThe clear filters action in the desktop sidebar.
drawer-backdropThe backdrop behind the mobile filter drawer.
drawer-panelThe mobile filter drawer panel.
drawer-actionsThe action area in the mobile filter drawer.
drawer-clearThe clear filters action in the mobile drawer.
drawer-doneThe done action in the mobile drawer.
drawer-closeThe button that closes the mobile filter drawer.
drawer-bodyThe content area of the mobile filter drawer.
drawer-filter-groupsThe filter groups container in the mobile drawer.
nbhd-filters::part(base) {
  /* your styles */
}

CSS Properties

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

Filters

PropertyTokenValue Copy
--nbhd-filters-display—block
--nbhd-filters-drawer-actions-size--nbhd-size-control-xl44px
--nbhd-filters-drawer-actions-zIndex--nbhd-z-11
--nbhd-filters-drawer-backdrop-background—rgb(from var(--nbhd-overlay-color) r g b / var(--nbhd-overlay-opacity))
--nbhd-filters-drawer-backdrop-zIndex--nbhd-z-10001000
--nbhd-filters-drawer-body-paddingBlock--nbhd-space-520px
--nbhd-filters-drawer-body-paddingInline--nbhd-space-520px
--nbhd-filters-drawer-close-icon-size--nbhd-size-icon-sm16px
--nbhd-filters-drawer-close-paddingBlock--nbhd-space-00px
--nbhd-filters-drawer-close-paddingInline--nbhd-space-312px
--nbhd-filters-drawer-close-zIndex--nbhd-z-1000010000
--nbhd-filters-drawer-panel-zIndex--nbhd-z-1000010000
--nbhd-filters-group-borderBlockEndStyle—solid
--nbhd-filters-group-borderBlockEndWidth--nbhd-border-width-subtle1px
--nbhd-filters-group-borderColor--nbhd-context-color-control-borderAdapts to surface
--nbhd-filters-group-paddingInline--nbhd-space-00px
--nbhd-filters-group-panel-expanded-maxBlockSize—none
--nbhd-filters-group-panel-expanded-paddingBlock--nbhd-space-0 --nbhd-space-40px 16px
--nbhd-filters-group-panel-maxBlockSize—0
--nbhd-filters-group-panel-paddingBlock--nbhd-space-00px
--nbhd-filters-group-panel-paddingInline--nbhd-space-00px
--nbhd-filters-group-panel-standalone-paddingBlock--nbhd-space-416px
--nbhd-filters-group-toggle-fontSize--nbhd-typography-body-fontSize1rem
--nbhd-filters-group-toggle-justifyContent—start
--nbhd-filters-group-toggle-paddingBlock--nbhd-space-520px
--nbhd-filters-group-toggle-paddingInline--nbhd-space-1 --nbhd-space-64px 24px
--nbhd-filters-group-toggle-textTransform—uppercase
--nbhd-filters-groups-borderBlockStartStyle—solid
--nbhd-filters-groups-borderBlockStartWidth--nbhd-border-width-subtle1px
--nbhd-filters-groups-borderColor--nbhd-context-color-control-borderAdapts to surface
--nbhd-filters-header-display—flex
--nbhd-filters-header-justifyContent—space-between
--nbhd-filters-hidden-display—none
--nbhd-filters-hidden-opacity—0
--nbhd-filters-hidden-visibility—hidden
--nbhd-filters-host-display—block
--nbhd-filters-inlineSize—100%
--nbhd-filters-marginBlock--nbhd-space-00px
--nbhd-filters-marginInline--nbhd-space-00px
--nbhd-filters-option-finish-size—24px
--nbhd-filters-option-toggle-fontSize--nbhd-typography-body-fontSize1rem
--nbhd-filters-option-toggle-marginBlock--nbhd-space-2 --nbhd-space-08px 0px
--nbhd-filters-options-expanded-maxBlockSize—400px
--nbhd-filters-options-maxBlockSize—0
--nbhd-filters-paddingBlock--nbhd-space-416px
--nbhd-filters-paddingInline--nbhd-space-052px
--nbhd-filters-position—relative
--nbhd-filters-selected-filter-alignItems—center
--nbhd-filters-selected-filter-backgroundColor--nbhd-base-color-neutral-100#eaebec
--nbhd-filters-selected-filter-display—flex
--nbhd-filters-selected-filter-fontSize--nbhd-typography-bodySmall-fontSize0.875rem
--nbhd-filters-selected-filter-fontWeight--nbhd-typography-bodySmall-fontWeight400
--nbhd-filters-selected-filter-gap--nbhd-space-28px
--nbhd-filters-selected-filter-marginBlock--nbhd-space-14px
--nbhd-filters-selected-filter-marginInline--nbhd-space-14px
--nbhd-filters-selected-filter-paddingBlock--nbhd-space-14px
--nbhd-filters-selected-filter-paddingInline--nbhd-space-14px
--nbhd-filters-selected-marginBlock--nbhd-space-312px
--nbhd-filters-tooltip-description-backgroundColor--nbhd-base-color-neutral-100#eaebec
--nbhd-filters-tooltip-description-borderRadius--nbhd-border-radius-md6px
--nbhd-filters-tooltip-description-inlineSize—200px
--nbhd-filters-tooltip-description-insetBlockEnd—125%
--nbhd-filters-tooltip-description-insetInlineStart—50%
--nbhd-filters-tooltip-description-paddingBlock--nbhd-space-28px
--nbhd-filters-tooltip-description-paddingInline--nbhd-space-312px
--nbhd-filters-tooltip-description-pointerEvents—none
--nbhd-filters-tooltip-description-position—absolute
--nbhd-filters-tooltip-description-textAlign—center
--nbhd-filters-tooltip-description-zIndex--nbhd-z-500500
--nbhd-filters-tooltip-display—inline-block
--nbhd-filters-tooltip-icon-color--nbhd-color-text-primary#1c1d1f
--nbhd-filters-tooltip-icon-fill--nbhd-base-color-neutral-400#a7a9ac
--nbhd-filters-tooltip-icon-size--nbhd-size-icon-sm16px
--nbhd-filters-tooltip-marginInline--nbhd-space-1 --nbhd-space-04px 0px
--nbhd-filters-tooltip-position—relative
--nbhd-filters-tooltip-verticalAlign—middle
--nbhd-filters-visible-display—block
--nbhd-filters-visible-opacity—1
--nbhd-filters-visible-visibility—visible

Form control

PropertyTokenValue Copy
--nbhd-formControl-display—inline
--nbhd-formControl-field-appearance—none
--nbhd-formControl-field-borderRadius--nbhd-border-radius-none0
--nbhd-formControl-field-color--nbhd-context-color-control-foregroundAdapts to surface
--nbhd-formControl-field-display—inline-block
--nbhd-formControl-field-fontFamily--nbhd-typography-body-fontFamilysans-serif
--nbhd-formControl-field-fontSize--nbhd-typography-body-fontSize1rem
--nbhd-formControl-field-inlineSize—100%
--nbhd-formControl-field-position—relative
--nbhd-formControl-fontFamily--nbhd-typography-body-fontFamilysans-serif
--nbhd-formControl-host-display—block
--nbhd-formControl-label-color--nbhd-context-color-text-primaryAdapts to surface
--nbhd-formControl-label-display—block
--nbhd-formControl-label-fontFamily--nbhd-typography-label-fontFamilysans-serif
--nbhd-formControl-label-fontSize--nbhd-typography-label-fontSize1rem
--nbhd-formControl-label-fontWeight--nbhd-typography-label-fontWeight600
--nbhd-formControl-label-letterSpacing—inherit
--nbhd-formControl-label-marginBlock--nbhd-space-0 --nbhd-space-050px 2px
--nbhd-formControl-label-position—relative
--nbhd-formControl-label-textTransform—inherit
--nbhd-formControl-marginBlock--nbhd-space-00px
--nbhd-formControl-maxInlineSize—100%
--nbhd-formControl-paddingBlock--nbhd-space-00px
--nbhd-formControl-paddingInline--nbhd-space-00px
--nbhd-formControl-position—relative
--nbhd-formControl-required-gap--nbhd-space-052px
--nbhd-formControl-text-marginBlock--nbhd-space-1 --nbhd-space-04px 0px

Overlay

PropertyTokenValue Copy
--nbhd-overlay-color--nbhd-color-overlay#000000
--nbhd-overlay-opacity--nbhd-opacity-overlay-backdrop0.5

Selection control

PropertyTokenValue Copy
--nbhd-selectionControl-box-blockSize—18px
--nbhd-selectionControl-box-borderColor--nbhd-context-color-control-borderAdapts to surface
--nbhd-selectionControl-box-borderRadius--nbhd-border-radius-sm2px
--nbhd-selectionControl-box-borderStyle—solid
--nbhd-selectionControl-box-borderWidth--nbhd-border-width-subtle1px
--nbhd-selectionControl-box-inlineSize—18px
--nbhd-selectionControl-checked-label-fontWeight—600
--nbhd-selectionControl-focus-outlineColor--nbhd-context-color-focus-outlineAdapts to surface
--nbhd-selectionControl-formControl-marginBlock--nbhd-space-14px
--nbhd-selectionControl-formControl-paddingBlock--nbhd-space-14px
--nbhd-selectionControl-host-display—block
--nbhd-selectionControl-indicator-backgroundColor—transparent
--nbhd-selectionControl-indicator-blockSize—10px
--nbhd-selectionControl-indicator-inlineSize—10px
--nbhd-selectionControl-indicator-marginInline--nbhd-space-1 --nbhd-space-04px 0px
--nbhd-selectionControl-label-alignItems—center
--nbhd-selectionControl-label-cursor—pointer
--nbhd-selectionControl-label-display—flex
--nbhd-selectionControl-label-fontWeight--nbhd-typography-body-fontWeight400
--nbhd-selectionControl-label-gap--nbhd-space-14px
--nbhd-selectionControl-label-justifyContent—start
--nbhd-selectionControl-label-paddingInline--nbhd-space-9 --nbhd-space-036px 0px
--nbhd-selectionControl-label-textTransform—normal
--nbhd-selectionControl-text-paddingInlineStart--nbhd-space-936px

Dependencies

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

Esc
↑ ↓ to move↵ to open