useFuzzyFilter

Installation

npx shadcn@latest add @cubby-ui/use-fuzzy-filter

Overview

useFuzzyFilter provides fuzzy matching capabilities using match-sorter. It returns filter functions that work with any list component, including Command and Autocomplete.

When to use:

Search across multiple fields (label, description, tags)
Relevance-sorted results (best matches first)
Flexible matching (acronyms, partial matches, typo tolerance)

Usage


import { useFuzzyFilter } from "@/hooks/cubby-ui/use-fuzzy-filter";
 
const { filter, filterItem } = useFuzzyFilter({
  keys: ["label", "description"],
  threshold: "contains",
});
 
// Filter and sort an array
const results = filter(items, query);
 
// Check if single item matches
const matches = filterItem(item, query);

Example with Command


import { useFuzzyFilter } from "@/hooks/cubby-ui/use-fuzzy-filter";
import { Command, CommandList, CommandItem } from "@/lib/cubby-ui/command";
 
function FuzzyCommand({ items }) {
  const [query, setQuery] = useState("");
 
  const { filter } = useFuzzyFilter({
    keys: ["label", "description"],
  });
 
  // Filter and sort by relevance
  const filteredItems = filter(items, query);
 
  return (
    <Command
      items={filteredItems}
      value={query}
      onValueChange={setQuery}
      filter={null} // Disable built-in filter since we're filtering externally
    >
      <CommandInput placeholder="Search..." />
      <CommandList>
        {filteredItems.map((item) => (
          <CommandItem key={item.id} value={item}>
            {item.label}
          </CommandItem>
        ))}
      </CommandList>
    </Command>
  );
}

API Reference

Options

Prop

Type

Default

Return Value

Property	Type	Description
`filter`	`(items: T[], query: string) => T[]`	Filters and sorts an array of items by relevance
`filterItem`	`(item: T, query: string) => boolean`	Checks if a single item matches. Use with component's `filter` prop

Filtering Patterns

External filtering with relevance sorting

Use filter when you want results sorted by relevance:


const { filter } = useFuzzyFilter({ keys: ["label"] });
const [query, setQuery] = useState("");
const filteredItems = filter(items, query);
 
<Command items={filteredItems} filter={null}>
  ...
</Command>

Internal filtering (boolean check)

Use filterItem for simple boolean filtering without relevance sorting:


const { filterItem } = useFuzzyFilter({ keys: ["label"] });
 
<Command filter={filterItem}>
  ...
</Command>

Used By

Command - For fuzzy search in command menus
Autocomplete - For fuzzy search in suggestions

On this page