Qif Documentation

FiltersProvider

The FiltersProvider component is the core of Qif. It manages the filter state and provides context to child components.

Props

• instance: FiltersContextValue<T> - The filters instance created by useFilters hook
• children: ReactNode - Child components that will have access to the filters context

useFilters Hook

The useFilters hook provides methods to create and manage filter states.

Options

• syncWithSearchParams?: boolean - Whether to sync filters with URL search params (default: true)
• parsers: UseQueryStatesKeysMap<T> - Object containing filter parsers with their default values

Parsers

Qif uses nuqs parsers to handle different data types in URL parameters. Here are the available built-in parsers:

• parseAsString - For string values with optional default value
• parseAsInteger - For integer values
• parseAsFloat - For floating-point numbers
• parseAsBoolean - For boolean values
• parseAsStringLiteral - For specific string values (type-safe)
• parseAsNumberLiteral - For specific number values (type-safe)
• parseAsArrayOf - For arrays of any other parser type
• parseAsJson - For complex JSON objects with validation

Example Usage

import { useFilters } from 'react-qif'
import { parseAsString, parseAsInteger, parseAsArrayOf } from 'nuqs'

const filtersInstance = useFilters({
  syncWithSearchParams: true,
  parsers: {
    search: parseAsString.withDefault(''),
    page: parseAsInteger.withDefault(1),
    categories: parseAsArrayOf(parseAsString).withDefault([])
  }
})

Return Value

• filters: T - Current filter values
• setValue(name: keyof T, value: T[K]) - Sets the value of a specific filter
• getValue(name: keyof T) - Gets the current value of a filter
• setFilters(newFilters: Partial<T>) - Updates multiple filter values at once
• unregister(name: keyof T) - Removes a filter
• reset() - Resets all filters to their default values
• isResetDisabled: boolean - Whether the reset action is disabled

useFiltersContext Hook

The useFiltersContext hook provides access to the filters context within child components.

Returns the same interface as useFilters hook. Must be used within a FiltersProvider component.