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.
Consumed interfaces
IFiltersProps
IInternalItem
API
Parameters
Input parameters accepted by this composable.
- propsrequiredIFiltersProps
- Filter configuration from the parent component: filterKeys, filterMode, noFilter, customFilter, customKeyFilter.
- itemsrequiredMaybeRef<T[]>
- The full item list to filter. Can be a plain array or a reactive ref.
- queryrequiredRef<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.customKeyFilterMaybeRef<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