useFilter

The useFilter hook provides functionality for filtering a list of options by their text value based on user input.

Import

import { useFilter } from "@cfa/react-core";

Features

• Filtering options in a combobox, select, or similar component based on user input
• Support for various filtering strategies including contains, startsWith, and custom functions
• Support for locale-specific string matching
• Support for case sensitivity customization

Usage

Standard Filtering

function Example() {
  const { contains } = useFilter({
    sensitivity: "base", // Options: 'base', 'accent', 'case', 'variant'
  });

  const sauces = [
    { id: "1", name: "Chick-fil-A® Sauce" },
    { id: "2", name: "Polynesian Sauce" },
    { id: "3", name: "Honey Mustard Sauce" },
    { id: "4", name: "Garden Herb Ranch Sauce" },
    { id: "5", name: "Barbeque Sauce" },
    { id: "6", name: "Sweet & Spicy Sriracha Sauce" },
    { id: "7", name: "Zesty Buffalo Sauce" },
  ];

  const [inputValue, setInputValue] = React.useState("");

  // Filter the sauces list based on the input value
  const filteredSauces = sauces.filter((sauce) =>
    contains(sauce.name, inputValue)
  );

  return (
    <div>
      <SearchInput
        value={inputValue}
        onChange={setInputValue}
        placeholder="Search sauces"
      />
      <ListBox.Root items={filteredSauces}>
        {(sauce) => <ListBox.Item id={sauce.id}>{sauce.name}</ListBox.Item>}
      </ListBox.Root>
    </div>
  );
}

Autocomplete

import { useFilter } from "@cfa/react-core";
import { Autocomplete } from "@cfa/react-core";

function Example() {
  const { contains } = useFilter({
    sensitivity: "base", // Options: 'base', 'accent', 'case', 'variant'
  });

  const sauces = [
    { id: "1", name: "Chick-fil-A® Sauce" },
    { id: "2", name: "Polynesian Sauce" },
    { id: "3", name: "Honey Mustard Sauce" },
    { id: "4", name: "Garden Herb Ranch Sauce" },
    { id: "5", name: "Barbeque Sauce" },
    { id: "6", name: "Sweet & Spicy Sriracha Sauce" },
    { id: "7", name: "Zesty Buffalo Sauce" },
  ];

  return (
    <Autocomplete filter={contains}>
      <SearchInput />
      <ListBox.Root items={sauces}>
        {(sauce) => <ListBox.Item id={sauce.id}>{sauce.name}</ListBox.Item>}
      </ListBox.Root>
    </Autocomplete>
  );
}

API

Parameters

The useFilter hook accepts the following options.

useFilter(options?: Intl.CollatorOptions): Filter

You can find more details on the Intl.Collator API for more information on the options.

The primary option you will use is sensitivity, which controls how the string comparison is done. The default value is 'base', which means that the comparison will ignore case and accents.

• sensitivity (optional) - The string matching sensitivity level to use when filtering
  • 'base' - Case and accent insensitive (default)
  • 'accent' - Case insensitive, accent sensitive
  • 'case' - Case sensitive, accent insensitive
  • 'variant' - Case and accent sensitive

useFilter({
  sensitivity: "base", // Options: 'base', 'accent', 'case', 'variant'
});

Return Value

The useFilter hook returns an object with the following filtering methods:

• startsWith(string, substring) - Returns whether string starts with substring
• endsWith(string, substring) - Returns whether string ends with substring
• contains(string, substring) - Returns whether string contains substring

Accessibility

The useFilter hook helps ensure that filtering functionality in components like comboboxes and select menus follows accessibility best practices:

• Case-insensitive filtering by default matches how users typically think about searching
• Locale-specific string matching handles international characters properly
• Support for different filtering strategies accommodates different user expectations

Source

This hook is a re-export from react-aria-components package. For more details, see the React Aria useFilter documentation.