useFilter

Commons
stable

Client-side filter engine for item lists. Applies a search query against one or more keys using the configured filter strategy (intersect, union, every, some). Supports custom per-key filter functions and a global custom filter override.

API

Signature

Full TypeScript signature sourced from the composable file.

typescript

Consumed interfaces

IFiltersProps
IInternalItem

API

Parameters

Input parameters accepted by this composable.

props
required
IFiltersProps
Filter configuration from the parent component: filterKeys, filterMode, noFilter, customFilter, customKeyFilter.
items
required
MaybeRef<T[]>
The full item list to filter. Can be a plain array or a reactive ref.
query
required
Ref<string | undefined> | (() => string | undefined)
The current search string. Accepts a ref or a getter function. An empty string disables filtering.
options
{ transform?: (item: T) => Record<string, unknown> customKeyFilter?: MaybeRef<TFilterKeyFunctions | undefined> }
options.transform
(item: T) => Record<string, unknown>
Optional function to derive the plain-object representation of an item before filtering (e.g. to flatten nested keys).
options.customKeyFilter
MaybeRef<TFilterKeyFunctions | undefined>
Composable-level per-key filter functions, merged on top of props.customKeyFilter. Useful for programmatic overrides independent of the template props.

API

Return values

Properties and methods exposed by the composable return object.

filteredItems
The subset of items that match the current query, in original order.
filteredMatches
Map from item value key to a record of matched ranges per field. Used to highlight matched substrings in the UI.
getMatches
Helper to retrieve the match record for a single item. Returns undefined when the item is not in filteredMatches.

Usage

Examples

Ready-to-paste usage snippets.

Search over a name list

vue