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.

πŸš€ Installation​

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

πŸ“– Usage​

import {FilterList} from '@nodeblocks/frontend-filter-list-block';
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>
  );
}

πŸ”§ 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
submitButtonLabelstringRequiredLabel for the submit/apply button (defaults to "Apply" in function signature)
resetButtonLabelstringRequiredLabel for the reset/clear button (defaults to "Reset" in function signature)
defaultSelectedFiltersFilterChild[][]Initial selected filters on component mount
classNamestringundefinedAdditional CSS class name for styling the container
childrenBlocksOverrideundefinedCustom block components to override default rendering

Note: The main component inherits all HTML div element 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​

PropTypeDefaultDescription
childFilterChildRequiredFilter item to display as a chip
onClickRemoveFilter(filter: FilterChild) => voidFrom contextCallback fired when chip is removed

Note: This component inherits all HTML div element props.

FilterList.SelectedFilterList​

PropTypeDefaultDescription
selectedFiltersFilterChild[]From contextList of currently selected filters
onClickRemoveFilter(filter: FilterChild) => voidFrom contextCallback for removing selected filters

Note: This component inherits all HTML div element props.

FilterList.AccordionArrow​

PropTypeDefaultDescription
isExpandedbooleanRequiredWhether the accordion is expanded

Note: This component inherits all HTML span element props.

FilterList.Accordion​

PropTypeDefaultDescription
childFilterChildRequiredFilter group to display as accordion

Note: This component inherits all HTML div element props.

FilterList.AccordionList​

PropTypeDefaultDescription
optionsFilterChild[]From contextList of filter options to display as accordions

Note: This component inherits all HTML div element props.

FilterList.ResetButton​

PropTypeDefaultDescription
childrenReactNodeContext resetButtonLabelButton content/text
onClick() => voidContext onClickResetFiltersClick handler for reset action
classNamestringundefinedAdditional CSS class name for styling

Note: This component inherits all HTML button element props.

FilterList.SubmitButton​

PropTypeDefaultDescription
childrenReactNodeContext submitButtonLabelButton content/text
onClick() => voidContext onApplyFilters with selected filtersClick handler for submit action
classNamestringundefinedAdditional CSS class name for styling

Note: This component inherits all HTML button element props.

FilterList.Actions​

PropTypeDefaultDescription
classNamestringundefinedAdditional CSS class name for styling the actions container

Note: This component inherits all HTML div element props. Renders a FilterList.ResetButton and FilterList.SubmitButton component.

πŸ”§ TypeScript Support​

Full TypeScript support with comprehensive type definitions:

import {FilterList} from '@nodeblocks/frontend-filter-list-block';
import {ComponentProps} from 'react';

// FilterChild type definition (not exported, define locally)
type FilterChild = {
  label: string;
  subtitle: string;
  value: string;
  groupName?: string;
  checked?: boolean;
  children?: FilterChild[];
  columns?: 1 | 2;
};

// Main component interface
interface FilterListProps extends ComponentProps<'div'> {
  options: FilterChild[];
  onApplyFilters: (selectedFilters: FilterChild[]) => void;
  onResetFilters: () => void;
  submitButtonLabel: string;
  resetButtonLabel: string;
  defaultSelectedFilters?: FilterChild[];
}

// Example usage with hierarchical filters
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'},
    ],
  },
];

// Advanced example with custom styling and handlers
function CustomFilterList() {
  const handleApplyFilters = (selectedFilters: FilterChild[]) => {
    console.log('Applied filters:', selectedFilters);
    // Process selected filters
  };

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

  return (
    <FilterList
      options={filterOptions}
      onApplyFilters={handleApplyFilters}
      onResetFilters={handleResetFilters}
      submitButtonLabel="Apply Filters"
      resetButtonLabel="Clear All"
      defaultSelectedFilters={[]}
      className="my-custom-filter-list">
      <FilterList.SelectedFilterList className="selected-chips" />
      <FilterList.AccordionList className="filter-accordions" />
      <FilterList.Actions className="filter-actions">
        <FilterList.ResetButton>Clear All</FilterList.ResetButton>
        <FilterList.SubmitButton>Apply Filters</FilterList.SubmitButton>
      </FilterList.Actions>
    </FilterList>
  );
}

Built with ❀️ using React, TypeScript, and modern web standards.