Skip to main content

Filter List Block

The FilterList Component is a fully customizable and accessible filter interface built with React and TypeScript. It provides a complete filtering experience with accordion-style filter groups, selected filter chips, and flexible customization options. Built on top of MUI components for consistent styling.

πŸš€ Installation​

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

πŸ“– Usage​

import {FilterList} from '@nodeblocks/frontend-filter-list-block';
Live Editor
function BasicFilterList() {
  const filterOptions = [
    {
      label: 'Category',
      subtitle: 'Filter by product category',
      value: 'category',
      columns: 2,
      children: [
        {label: 'Electronics', value: 'electronics', subtitle: '', groupName: 'category'},
        {label: 'Clothing', value: 'clothing', subtitle: '', groupName: 'category'},
        {label: 'Books', value: 'books', subtitle: '', groupName: 'category'},
        {label: 'Home & Garden', value: 'home-garden', subtitle: '', groupName: 'category'},
      ],
    },
    {
      label: 'Price Range',
      subtitle: 'Select your budget',
      value: 'price',
      columns: 1,
      children: [
        {label: 'Under $25', value: 'under-25', subtitle: '', groupName: 'price'},
        {label: '$25 - $50', value: '25-50', subtitle: '', groupName: 'price'},
        {label: '$50 - $100', value: '50-100', subtitle: '', groupName: 'price'},
        {label: 'Over $100', value: 'over-100', subtitle: '', groupName: 'price'},
      ],
    },
  ];

  return (
    <FilterList
      options={filterOptions}
      submitButtonLabel="Apply Filters"
      resetButtonLabel="Clear All"
      onApplyFilters={selectedFilters => {
        console.log('Applied filters:', selectedFilters);
      }}
      onResetFilters={() => {
        console.log('Filters reset');
      }}
      defaultSelectedFilters={[]}
    >
      <FilterList.SelectedFilterList />
      <FilterList.AccordionList />
      <FilterList.Actions />
    </FilterList>
  );
}
Result
Loading...

πŸ”§ Props Reference​

Main Component Props​

PropTypeDefaultDescription
optionsFilterChild[]RequiredArray of filter options with hierarchical structure
onApplyFilters(selectedFilters: FilterChild[]) => voidRequiredCallback function triggered when filters are applied
onResetFilters() => voidRequiredCallback function triggered when filters are reset
submitButtonLabelstring'Apply'Label for the submit/apply button
resetButtonLabelstring'Reset'Label for the reset/clear button
defaultSelectedFiltersFilterChild[][]Initial selected filters on component mount
classNamestringundefinedAdditional CSS class name for styling the container
sxSxProps<Theme>{ backgroundColor: 'background.paper' }MUI system props for custom styling
childrenBlocksOverrideundefinedCustom block components to override default rendering

Note: This component inherits all MUI Stack component props.

Sub-Components​

The FilterList component provides several sub-components. All sub-components receive their default values from the main component's context and can override these values through props.

FilterList.FilterChip​

Renders a selected filter as a removable chip using MUI Chip.

PropTypeDefaultDescription
childFilterChildRequiredFilter item to display as a chip
onClickRemoveFilter(filter: FilterChild) => voidContext valueCallback fired when chip is removed
classNamestringundefinedAdditional CSS class name for styling
sxSxProps<Theme>undefinedMUI system props for custom styling

Note: This component inherits all MUI Chip component props.

FilterList.SelectedFilterList​

Renders the list of currently selected filters using MUI Box.

PropTypeDefaultDescription
selectedFiltersFilterChild[]Context valueList of currently selected filters
onClickRemoveFilter(filter: FilterChild) => voidContext valueCallback for removing selected filters
classNamestringundefinedAdditional CSS class name for styling
sxSxProps<Theme>undefinedMUI system props for custom styling

Note: This component inherits all MUI Box component props. Returns null when no filters are selected.

FilterList.AccordionArrow​

Renders the accordion expand/collapse arrow icon using MUI Box (as span).

PropTypeDefaultDescription
classNamestringundefinedAdditional CSS class name for styling
sxSxProps<Theme>undefinedMUI system props for custom styling

Note: This component inherits all MUI Box component props (rendered as component="span"). Uses MUI NavigateNextIcon and rotates 90Β° when expanded.

FilterList.Accordion​

Renders a filter group as an expandable accordion using MUI Accordion.

PropTypeDefaultDescription
childFilterChildRequiredFilter group to display as accordion
selectedFiltersFilterChild[]Context valueCurrently selected filters (overrides context)
onChangeCheckbox(item: FilterChild) => voidContext valueCheckbox change callback (overrides context)
classNamestringundefinedAdditional CSS class name for styling
sxSxProps<Theme>undefinedMUI system props for custom styling

Note: This component inherits all MUI Accordion component props (except children).

FilterList.AccordionList​

Renders the list of filter accordions using MUI Box.

PropTypeDefaultDescription
optionsFilterChild[]Context valueList of filter options to display as accordions
classNamestringundefinedAdditional CSS class name for styling
sxSxProps<Theme>undefinedMUI system props for custom styling

Note: This component inherits all MUI Box component props.

FilterList.ResetButton​

Renders the reset/clear button using MUI Button.

PropTypeDefaultDescription
resetButtonLabelReactNodeContext valueButton label (overrides context)
onClickResetFilters() => voidContext valueReset callback (overrides context)
childrenReactNodeContext resetButtonLabelButton content - overrides resetButtonLabel
onClick() => voidContext onClickResetFiltersClick handler - overrides onClickResetFilters
classNamestringundefinedAdditional CSS class name for styling
sxSxProps<Theme>undefinedMUI system props for custom styling
variantButtonVariant'outlined'MUI Button variant

Note: This component inherits all MUI Button component props.

FilterList.SubmitButton​

Renders the submit/apply button using MUI Button.

PropTypeDefaultDescription
submitButtonLabelReactNodeContext valueButton label (overrides context)
onApplyFilters(filters: FilterChild[]) => voidContext valueApply callback (overrides context)
selectedFiltersFilterChild[]Context valueSelected filters to pass to callback (overrides context)
childrenReactNodeContext submitButtonLabelButton content - overrides submitButtonLabel
onClick() => voidCalls onApplyFilters with selectedFiltersClick handler - overrides default behavior
classNamestringundefinedAdditional CSS class name for styling
sxSxProps<Theme>undefinedMUI system props for custom styling
variantButtonVariant'contained'MUI Button variant

Note: This component inherits all MUI Button component props.

FilterList.Actions​

Renders the action buttons container using MUI Box.

PropTypeDefaultDescription
classNamestringundefinedAdditional CSS class name for styling the actions container
sxSxProps<Theme>undefinedMUI system props for custom styling

Note: This component inherits all MUI Box component props. Renders FilterList.ResetButton and FilterList.SubmitButton components.

🎨 Configuration examples​

Custom Selected Filters Styling​

<FilterList.SelectedFilterList 
  sx={{ 
    bgcolor: 'primary.light',
    borderRadius: 2,
    p: 2
  }} 
/>

Custom Button Styling​

<FilterList.Actions sx={{ justifyContent: 'flex-end', gap: 2 }}>
  <FilterList.ResetButton 
    variant="text"
    sx={{ color: 'text.secondary' }}>
    Clear All
  </FilterList.ResetButton>
  <FilterList.SubmitButton 
    variant="contained"
    color="primary"
    sx={{ minWidth: 120 }}>
    Apply Filters
  </FilterList.SubmitButton>
</FilterList.Actions>

πŸ”§ TypeScript Support​

Full TypeScript support with comprehensive type definitions:

import {FilterList} from '@nodeblocks/frontend-filter-list-block';
import {StackProps, ChipProps, ButtonProps, BoxProps} from '@mui/material';

// FilterChild type definition
type FilterChild = {
  label: string;
  subtitle: string;
  value: string;
  groupName?: string;
  checked?: boolean;
  children?: FilterChild[];
  columns?: number;
};

// Main component props extend MUI StackProps
interface FilterListProps extends Omit<StackProps, 'children'> {
  options: FilterChild[];
  onApplyFilters: (selectedFilters: FilterChild[]) => void;
  onResetFilters: () => void;
  submitButtonLabel?: string;
  resetButtonLabel?: string;
  defaultSelectedFilters?: FilterChild[];
  children?: BlocksOverride;
}

// Example with MUI styling
function TypedFilterListExample() {
  const filterOptions: FilterChild[] = [
    {
      label: 'Brand',
      subtitle: 'Select preferred brands',
      value: 'brand',
      columns: 2,
      children: [
        {label: 'Apple', value: 'apple', subtitle: '', groupName: 'brand'},
        {label: 'Samsung', value: 'samsung', subtitle: '', groupName: 'brand'},
        {label: 'Google', value: 'google', subtitle: '', groupName: 'brand'},
      ],
    },
    {
      label: 'Price Range',
      subtitle: 'Filter by price',
      value: 'price',
      columns: 1,
      children: [
        {label: 'Under $100', value: 'under-100', subtitle: '', groupName: 'price'},
        {label: '$100 - $500', value: '100-500', subtitle: '', groupName: 'price'},
      ],
    },
  ];

  const handleApplyFilters = (selectedFilters: FilterChild[]): void => {
    console.log('Applied filters:', selectedFilters);
  };

  const handleResetFilters = (): void => {
    console.log('Filters reset');
  };

  return (
    <FilterList
      options={filterOptions}
      onApplyFilters={handleApplyFilters}
      onResetFilters={handleResetFilters}
      submitButtonLabel="Apply Filters"
      resetButtonLabel="Clear All"
      defaultSelectedFilters={[]}
      className="my-custom-filter-list"
      sx={{maxWidth: 400, mx: 'auto'}}
    >
      <FilterList.SelectedFilterList sx={{bgcolor: 'grey.100'}} />
      <FilterList.AccordionList />
      <FilterList.Actions sx={{gap: 2}}>
        <FilterList.ResetButton variant="text">Clear</FilterList.ResetButton>
        <FilterList.SubmitButton color="secondary">Apply</FilterList.SubmitButton>
      </FilterList.Actions>
    </FilterList>
  );
}

πŸ“ Notes​

  • The component uses MUI's Stack for the main layout with default backgroundColor: 'background.paper'
  • Selected filters are displayed as MUI Chip components with a close icon
  • Filter groups use MUI Accordion with NavigateNextIcon that rotates when expanded
  • Filter options within groups use MUI Checkbox with FormControlLabel
  • The columns property on FilterChild controls the grid layout of checkboxes within accordion details
  • The SelectedFilterList returns null when there are no selected filters
  • Reset button uses variant="outlined" by default
  • Submit button uses variant="contained" by default with flexGrow: 1
  • All sub-components support the sx prop for MUI system styling
  • Block override pattern allows inserting custom blocks between default blocks

Built with ❀️ using React, TypeScript, and MUI.