createFilter

A composable for filtering arrays of items based on search queries, supporting both primitive values and complex objects with customizable filtering logic.

Copy Markdown

Preview Intermediate Apr 5, 2026

Usage

The createFilter composable provides reactive array filtering with multiple modes for different search behaviors. It works with both primitive values and complex objects, and supports filtering by specific keys.

import { ref, shallowRef } from 'vue'
import { createFilter } from '@vuetify/v0'

const query = shallowRef('doe')
const items = ref([
  { name: 'John Doe', age: 30, city: 'New York' },
  { name: 'Jane Doe', age: 25, city: 'Los Angeles' },
  { name: 'Peter Jones', age: 40, city: 'Chicago' },
])

const filter = createFilter({ keys: ['name'] })
const { items: filtered } = filter.apply(query, items)

console.log(filtered.value)
// [
//   { name: 'John Doe', age: 30, city: 'New York' },
//   { name: 'Jane Doe', age: 25, city: 'Los Angeles' }
// ]

Context / DI

Use createFilterContext when you need to share a filter instance across a component tree:

import { createFilterContext } from '@vuetify/v0'

export const [useSearchFilter, provideSearchFilter, searchFilter] =
  createFilterContext({
    namespace: 'app:search',
    mode: 'union',
    keys: ['title', 'description'],
  })

// In parent component
provideSearchFilter()

// In child component
const filter = useSearchFilter()
const { items: filtered } = filter.apply(query, products)

Returns the standard trinity [useSearchFilter, provideSearchFilter, searchFilter]. The third element gives standalone access without injection — useful for testing and server-side use.

Options

Option	Type	Default	Notes
`mode`	`'some' \| 'every' \| 'union' \| 'intersection'`	`'some'`	Multi-query matching strategy. See Filter Modes below
`keys`	`string[]`	—	Object keys to filter on. When omitted, all values are checked
`customFilter`	`(query, item) => boolean`	—	Bypass built-in logic entirely with a custom predicate

// Filter only by name + email, using intersection mode
const filter = createFilter({
  keys: ['name', 'email'],
  mode: 'intersection',
})

// Custom filter (overrides keys and mode)
const filter = createFilter({
  customFilter: (query, item) =>
    String(item.name).toLowerCase().startsWith(String(query).toLowerCase()),
})

Architecture

createFilter provides pure filtering logic with context support:

Reactivity

Property/Method	Reactive	Notes
`query`		ShallowRef, updated on each `apply()`
`items` (from apply)		Computed, filters reactively

Tip

Reactive filtering Both the query and items passed to apply() can be reactive. The filtered result automatically updates when either changes.

Filter Modes

When the query is an array, each mode controls how multiple queries are matched against item values:

Mode	Behavior	Passes when
`some` (default)	Iterates all queries and all values	Any query matches any value
`every`	Iterates all queries and all values	All queries match all values
`union`	Joins values, checks each query	Any query matches the joined string
`intersection`	Joins values, checks each query	All queries match the joined string

Tip

some vs union some and union both pass when any query matches, but some checks each value independently while union joins all values into a single string. The difference matters when a match spans multiple fields.

Examples

API Reference

The following API details are for the createFilter composable.

createFilter

3 functions, 3 options, 4 properties, 1 method