Skip to main content

Filter List Block

FilterList is a controlled filter panel block built on MUI with accordion groups, selected filter chips, and apply/reset actions.

Installation​

npm install @nodeblocks/frontend-filter-list-block

What You Need​

ItemWhy it matters
dataSingle source of truth for selected filters (data.filters)
onDataChangeReceives updated state + metadata when filters change
optionsDefines accordion groups, checkbox options, and optional maxFilters caps
labels (optional)Overrides default Apply/Reset button text
Controlled component

FilterList does not own filter state. Keep state in your app and pass it through data.

Code Examples​

Live Editor
function Example() {
  const filterOptions = [
    {
      maxFilters: 2,
      groupName: 'Category',
      subtitle: 'Filter by product category',
      options: [
        {key: 'category', value: 'electronics', label: 'Electronics'},
        {key: 'category', value: 'clothing', label: 'Clothing'},
        {key: 'category', value: 'books', label: 'Books'},
        {key: 'category', value: 'home-garden', label: 'Home & Garden'},
      ],
    },
    {
      maxFilters: 3,
      groupName: 'Price Range',
      subtitle: 'Select your budget',
      options: [
        {key: 'price', value: 'under-25', label: 'Under $25', layout: 'full-width'},
        {key: 'price', value: '25-50', label: '$25 - $50'},
        {key: 'price', value: '50-100', label: '$50 - $100'},
        {key: 'price', value: 'over-100', label: 'Over $100'},
      ],
    },
  ];

  const defaultData = {filters: []};
  const [filters, setFilters] = React.useState(defaultData);

  const handleDataChange = nextData => {
    setFilters(nextData);
  };

  return <FilterList data={filters} options={filterOptions} onDataChange={handleDataChange} />;
}
Result
Loading...

Important Props​

Core Props​

PropTypeRequiredDefaultDescription
dataFilterListFormData ({ filters: { key: string; value: string }[] })Yes-Current filter state; each selected filter is a { key, value } row under data.filters
onDataChange(data, meta) => voidYes-Called on updates; meta includes name, value, cause (input, change, blur, clear, reset, programmatic), optional event
errors{ [fieldName: string]: string | string[] }NoundefinedField errors keyed by data field name (e.g. filters); passed through context but not rendered by default blocks

Content Props​

PropTypeRequiredDefaultDescription
optionsFilterListOption[]NoundefinedNested accordion structure: each node may define options (checkboxes), groups (nested accordions), optional maxFilters, groupName, and subtitle
labels{ submitButton?: ReactNode; resetButton?: ReactNode }NosubmitButton: 'Apply', resetButton: 'Reset'Override default button content
onResetFilters() => voidNoundefinedCalled after the reset button clears data.filters

Each FilterListOption checkbox entry uses { key, value, label } with optional layout (flexible or full-width). Set maxFilters on a group to cap selections in that subtree (including nested groups).

Layout and Composition Props​

PropTypeRequiredDefaultDescription
childrenBlocksOverride | ReactNodeNoundefinedOverride default blocks or provide custom JSX children
classNamestringNoundefinedClass name for the root container
sxSxPropsNoundefinedMUI system styles for the root container

FilterList also inherits StackProps (except children) and renders as a form, so standard form/stack props like onSubmit, id, and noValidate are supported. Default block order without overrides: selectedFilterList, accordionList, actions (defaultBlockOrder).

Default UI Blocks​

BlockBuilt onNotes
FilterList (root)Stack rendered as formProvides controlled context and renders default blocks in selectedFilterList, accordionList, actions order
FilterList.SelectedFilterListBox + ChipRow of removable selected-filter chips (hidden when empty)
FilterList.AccordionListBox + AccordionScrollable list of filter groups
FilterList.ActionsStack + ButtonReset and submit buttons

Extra field primitives​

PrimitiveBuilt onNotes
FilterList.CheckboxFieldCheckbox + FormControlLabelSingle filter checkbox; respects maxFilters from options
FilterList.FilterChipChipOne selected filter chip with delete button
FilterList.AccordionAccordion + TypographyOne filter group (summary, subtitle, options grid, nested groups)
FilterList.ResetButtonButtonClears all filters (variant="outlined")
FilterList.SubmitButtonButtonForm submit button (variant="contained", type="submit")

TypeScript​

import * as React from 'react';
import {FilterList, FilterListFormData, FilterListOption} from '@nodeblocks/frontend-filter-list-block';

type ProductFilterData = FilterListFormData & {
  searchText?: string;
};

const options: FilterListOption[] = [
  {
    groupName: 'Category',
    subtitle: 'Filter by product category',
    options: [
      {key: 'category', value: 'electronics', label: 'Electronics'},
      {key: 'category', value: 'clothing', label: 'Clothing'},
    ],
  },
];

export function ProductFilters() {
  const [data, setData] = React.useState<ProductFilterData>({filters: []});

  return (
    <FilterList<ProductFilterData>
      data={data}
      options={options}
      labels={{submitButton: 'Apply filters', resetButton: 'Clear all'}}
      onDataChange={setData}
      onSubmit={event => {
        event.preventDefault();
        console.log('apply', data.filters);
      }}
    />
  );
}