Filters
ReadyFilters component provides a user-friendly interface for refining search or data results.
Preview
Code
npm install @fbin-web/neighborhood-core
import { NbhdFilters } from '@fbin-web/neighborhood-core';
<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>
npm install @fbin-web/neighborhood-react
import { NbhdFilters } from '@fbin-web/neighborhood-react';
import { NbhdFilters } from '@fbin-web/neighborhood-react';
const 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' }],
},
];
const App = () => (
<>
<NbhdFilters
totalResults={10}
filters={filters}></NbhdFilters>
</>
);
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
filters | — | FilterGroup[] | [] | Array of filter groups and their options. This property is not settable via attribute. |
surface | surface | noneprimarysecondaryinverseinverse-secondary | primary | Surface color for the component. |
heading | heading | string | Filters | Heading displayed for the filters component. |
headingLevel | heading-level | 123456 | 4 | Level of the "Filters" heading. Match it to the page outline. |
clearFiltersLabel | clear-filters-label | string | Remove all | Label for the button that clears all selected filters. |
maxVisibleOptions | max-visible-options | number | 3 | Maximum number of filter options displayed before the expand button is shown. |
expandLabel | expand-label | string | Show more | Label for the button that displays additional filter options. |
collapseLabel | collapse-label | string | Show less | Label for the button that hides additional filter options. |
totalResults | total-results | number | 0 | Total number of results used to determine whether a filter group should be visually hidden. |
countStyle | count-style | roundsquarecurly | square | Bracket style used to display filter option counts. |
removeFilterLabel | remove-filter-label | string | Remove filter | Prefix for each selected-filter chip’s accessible name, e.g. "Remove filter: Chrome". |
resultsAnnouncement | results-announcement | string | {count} results | Announced to screen readers after a filter change once `total-results` updates. `{count}` is replaced with the result count. |
drawerLabel | drawer-label | string | Results filter options | Accessible name of the mobile filters drawer. |
resetLabel | reset-label | string | Reset | Text of the drawer's Reset button. |
resetAriaLabel | reset-aria-label | string | — | 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. |
doneLabel | done-label | string | Done | Text of the drawer's Done button. |
doneAriaLabel | done-aria-label | string | — | Accessible name for the Done button. Defaults to "Done, close filters", or to `done-label` when that has been changed. |
closeLabel | close-label | string | Close filters | Accessible name of the drawer's close button. |
No properties match.
Filter Group Structure
Structure for FilterGroup objects used in the filters property.
| Property | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Unique identifier for the filter group. |
title | string | No | Display title for the filter group. |
description | string | No | Plain text shown under the filter group's options. HTML is shown as text, not rendered. |
expanded | boolean | No | Whether the filter group is expanded by default. |
tooltip | string | No | Tooltip text to display for the filter group. |
options | FilterOption[] | No | Array of filter options within this group. |
No filter group structure match.
Filter Option Structure
Structure for FilterOption objects used within the FilterGroup options property.
| Property | Type | Required | Description |
|---|---|---|---|
label | string | Yes | Display label for the filter option. |
count | number | No | Number of results for this filter option. |
tooltip | string | No | Tooltip text for the filter option. |
selected | boolean | No | Whether the filter option is currently selected. |
href | string | No | URL associated with the filter option. |
value | string | No | Value associated with the filter option. |
finishImage | string | No | Image URL for finish-related filter options. |
No filter option structure match.
Events
| Name | Description | Event Detail |
|---|---|---|
nbhd-filter-change | Emitted when filter selections change. | { selectedFilters: FilterOptionEmitted[] } |
CSS Parts
| Name | Description |
|---|---|
base | The root filters component container. |
sidebar | The desktop sidebar container. |
sidebar-filter-groups | The filter groups container in the desktop sidebar. |
drawer | The mobile filter drawer container. |
header | The filters header containing the heading and clear action. |
heading | The filters heading text element. |
selected-filters | The container for selected filter buttons. |
selected-filter | An individual selected filter button. |
filter-group-toggle | The button that expands or collapses a filter group. |
filter-group-panel | The expandable panel containing a filter group's options. |
checkbox | An individual filter option checkbox. |
image | The finish image wrapper for filter options with finish images. |
tooltip | The filter tooltip container. |
tooltip-description | The filter tooltip description text. |
sidebar-clear | The clear filters action in the desktop sidebar. |
drawer-backdrop | The backdrop behind the mobile filter drawer. |
drawer-panel | The mobile filter drawer panel. |
drawer-actions | The action area in the mobile filter drawer. |
drawer-clear | The clear filters action in the mobile drawer. |
drawer-done | The done action in the mobile drawer. |
drawer-close | The button that closes the mobile filter drawer. |
drawer-body | The content area of the mobile filter drawer. |
drawer-filter-groups | The filter groups container in the mobile drawer. |
No css parts match.
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
| Property | Token | Value | Copy |
|---|---|---|---|
--nbhd-filters-display | — | block |
|
--nbhd-filters-drawer-actions-size | --nbhd-size-control-xl | 44px |
|
--nbhd-filters-drawer-actions-zIndex | --nbhd-z-1 | 1 |
|
--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-1000 | 1000 |
|
--nbhd-filters-drawer-body-paddingBlock | --nbhd-space-5 | 20px |
|
--nbhd-filters-drawer-body-paddingInline | --nbhd-space-5 | 20px |
|
--nbhd-filters-drawer-close-icon-size | --nbhd-size-icon-sm | 16px |
|
--nbhd-filters-drawer-close-paddingBlock | --nbhd-space-0 | 0px |
|
--nbhd-filters-drawer-close-paddingInline | --nbhd-space-3 | 12px |
|
--nbhd-filters-drawer-close-zIndex | --nbhd-z-10000 | 10000 |
|
--nbhd-filters-drawer-panel-zIndex | --nbhd-z-10000 | 10000 |
|
--nbhd-filters-group-borderBlockEndStyle | — | solid |
|
--nbhd-filters-group-borderBlockEndWidth | --nbhd-border-width-subtle | 1px |
|
--nbhd-filters-group-borderColor | --nbhd-context-color-control-border | Adapts to surface | |
--nbhd-filters-group-paddingInline | --nbhd-space-0 | 0px |
|
--nbhd-filters-group-panel-expanded-maxBlockSize | — | none |
|
--nbhd-filters-group-panel-expanded-paddingBlock | --nbhd-space-0 --nbhd-space-4 | 0px 16px |
|
--nbhd-filters-group-panel-maxBlockSize | — | 0 |
|
--nbhd-filters-group-panel-paddingBlock | --nbhd-space-0 | 0px |
|
--nbhd-filters-group-panel-paddingInline | --nbhd-space-0 | 0px |
|
--nbhd-filters-group-panel-standalone-paddingBlock | --nbhd-space-4 | 16px |
|
--nbhd-filters-group-toggle-fontSize | --nbhd-typography-body-fontSize | 1rem |
|
--nbhd-filters-group-toggle-justifyContent | — | start |
|
--nbhd-filters-group-toggle-paddingBlock | --nbhd-space-5 | 20px |
|
--nbhd-filters-group-toggle-paddingInline | --nbhd-space-1 --nbhd-space-6 | 4px 24px |
|
--nbhd-filters-group-toggle-textTransform | — | uppercase |
|
--nbhd-filters-groups-borderBlockStartStyle | — | solid |
|
--nbhd-filters-groups-borderBlockStartWidth | --nbhd-border-width-subtle | 1px |
|
--nbhd-filters-groups-borderColor | --nbhd-context-color-control-border | Adapts 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-0 | 0px |
|
--nbhd-filters-marginInline | --nbhd-space-0 | 0px |
|
--nbhd-filters-option-finish-size | — | 24px |
|
--nbhd-filters-option-toggle-fontSize | --nbhd-typography-body-fontSize | 1rem |
|
--nbhd-filters-option-toggle-marginBlock | --nbhd-space-2 --nbhd-space-0 | 8px 0px |
|
--nbhd-filters-options-expanded-maxBlockSize | — | 400px |
|
--nbhd-filters-options-maxBlockSize | — | 0 |
|
--nbhd-filters-paddingBlock | --nbhd-space-4 | 16px |
|
--nbhd-filters-paddingInline | --nbhd-space-05 | 2px |
|
--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-fontSize | 0.875rem |
|
--nbhd-filters-selected-filter-fontWeight | --nbhd-typography-bodySmall-fontWeight | 400 |
|
--nbhd-filters-selected-filter-gap | --nbhd-space-2 | 8px |
|
--nbhd-filters-selected-filter-marginBlock | --nbhd-space-1 | 4px |
|
--nbhd-filters-selected-filter-marginInline | --nbhd-space-1 | 4px |
|
--nbhd-filters-selected-filter-paddingBlock | --nbhd-space-1 | 4px |
|
--nbhd-filters-selected-filter-paddingInline | --nbhd-space-1 | 4px |
|
--nbhd-filters-selected-marginBlock | --nbhd-space-3 | 12px |
|
--nbhd-filters-tooltip-description-backgroundColor | --nbhd-base-color-neutral-100 | #eaebec |
|
--nbhd-filters-tooltip-description-borderRadius | --nbhd-border-radius-md | 6px |
|
--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-2 | 8px |
|
--nbhd-filters-tooltip-description-paddingInline | --nbhd-space-3 | 12px |
|
--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-500 | 500 |
|
--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-sm | 16px |
|
--nbhd-filters-tooltip-marginInline | --nbhd-space-1 --nbhd-space-0 | 4px 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 |
No filters match.
Form control
| Property | Token | Value | Copy |
|---|---|---|---|
--nbhd-formControl-display | — | inline |
|
--nbhd-formControl-field-appearance | — | none |
|
--nbhd-formControl-field-borderRadius | --nbhd-border-radius-none | 0 |
|
--nbhd-formControl-field-color | --nbhd-context-color-control-foreground | Adapts to surface | |
--nbhd-formControl-field-display | — | inline-block |
|
--nbhd-formControl-field-fontFamily | --nbhd-typography-body-fontFamily | sans-serif |
|
--nbhd-formControl-field-fontSize | --nbhd-typography-body-fontSize | 1rem |
|
--nbhd-formControl-field-inlineSize | — | 100% |
|
--nbhd-formControl-field-position | — | relative |
|
--nbhd-formControl-fontFamily | --nbhd-typography-body-fontFamily | sans-serif |
|
--nbhd-formControl-host-display | — | block |
|
--nbhd-formControl-label-color | --nbhd-context-color-text-primary | Adapts to surface | |
--nbhd-formControl-label-display | — | block |
|
--nbhd-formControl-label-fontFamily | --nbhd-typography-label-fontFamily | sans-serif |
|
--nbhd-formControl-label-fontSize | --nbhd-typography-label-fontSize | 1rem |
|
--nbhd-formControl-label-fontWeight | --nbhd-typography-label-fontWeight | 600 |
|
--nbhd-formControl-label-letterSpacing | — | inherit |
|
--nbhd-formControl-label-marginBlock | --nbhd-space-0 --nbhd-space-05 | 0px 2px |
|
--nbhd-formControl-label-position | — | relative |
|
--nbhd-formControl-label-textTransform | — | inherit |
|
--nbhd-formControl-marginBlock | --nbhd-space-0 | 0px |
|
--nbhd-formControl-maxInlineSize | — | 100% |
|
--nbhd-formControl-paddingBlock | --nbhd-space-0 | 0px |
|
--nbhd-formControl-paddingInline | --nbhd-space-0 | 0px |
|
--nbhd-formControl-position | — | relative |
|
--nbhd-formControl-required-gap | --nbhd-space-05 | 2px |
|
--nbhd-formControl-text-marginBlock | --nbhd-space-1 --nbhd-space-0 | 4px 0px |
No form control match.
Overlay
| Property | Token | Value | Copy |
|---|---|---|---|
--nbhd-overlay-color | --nbhd-color-overlay | #000000 |
|
--nbhd-overlay-opacity | --nbhd-opacity-overlay-backdrop | 0.5 |
Selection control
| Property | Token | Value | Copy |
|---|---|---|---|
--nbhd-selectionControl-box-blockSize | — | 18px |
|
--nbhd-selectionControl-box-borderColor | --nbhd-context-color-control-border | Adapts to surface | |
--nbhd-selectionControl-box-borderRadius | --nbhd-border-radius-sm | 2px |
|
--nbhd-selectionControl-box-borderStyle | — | solid |
|
--nbhd-selectionControl-box-borderWidth | --nbhd-border-width-subtle | 1px |
|
--nbhd-selectionControl-box-inlineSize | — | 18px |
|
--nbhd-selectionControl-checked-label-fontWeight | — | 600 |
|
--nbhd-selectionControl-focus-outlineColor | --nbhd-context-color-focus-outline | Adapts to surface | |
--nbhd-selectionControl-formControl-marginBlock | --nbhd-space-1 | 4px |
|
--nbhd-selectionControl-formControl-paddingBlock | --nbhd-space-1 | 4px |
|
--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-0 | 4px 0px |
|
--nbhd-selectionControl-label-alignItems | — | center |
|
--nbhd-selectionControl-label-cursor | — | pointer |
|
--nbhd-selectionControl-label-display | — | flex |
|
--nbhd-selectionControl-label-fontWeight | --nbhd-typography-body-fontWeight | 400 |
|
--nbhd-selectionControl-label-gap | --nbhd-space-1 | 4px |
|
--nbhd-selectionControl-label-justifyContent | — | start |
|
--nbhd-selectionControl-label-paddingInline | --nbhd-space-9 --nbhd-space-0 | 36px 0px |
|
--nbhd-selectionControl-label-textTransform | — | normal |
|
--nbhd-selectionControl-text-paddingInlineStart | --nbhd-space-9 | 36px |
No selection control match.
Dependencies
Child components <nbhd-filters> renders internally. Import them too when you tree-shake.