React Query Filters

@veebisepad/react-query-filters is a utility hook for managing URL query parameters in React.

It works well with Spatie laravel-query-builder and Inertia.js for filtering and sorting data in Laravel applications.

Installation

npm install @veebisepad/react-query-filters

Usage at a glance

React state is immutable, so the hook returns values (read in render) plus methods to change them:

• read: filters.values.name
• text/select input: {...filters.bind('name')}
• toggle a value in a multiple filter: filters.toggle('cat', value)
• apply: filters.get()

Features

• URL-synced filters: initial state is parsed from the current URL query string.
• Filter types via the factory:
  • single: a single value (text input, dropdown).
  • multiple: an array of values (multi-select, checkboxes).
  • range: a { from, to } range (date/price ranges).
  • custom: a fully custom filter.
• Utility methods: get, toQueryObject, toOrderedQueryObject, toSearchParams, clear, clearAll, has, data.

API

useFilters(filters, options)

Initializes filters from the URL and returns their values plus methods.

Parameters

• filters: object mapping each filter name to a filter created with the factory.

import { useFilters, factory } from '@veebisepad/react-query-filters';

const filters = useFilters({
    name: factory.single<string>(),
    category: factory.multiple<string>(),
    price: factory.range<number>(),
});

• options (optional):
  • delimiter (default ','): separator for multiple/range values in the URL.
  • onApply(queryObject): called by get() with the current query object.
  • preserveQueryOrder (default true): keep query params in their URL order.
  • location: a Location/URL-like object to use instead of window.location (SSR).

const filters = useFilters(
    {
        name: factory.single<string>(),
        category: factory.multiple<string>(),
        price: factory.range<number>(),
    },
    {
        onApply(queryObject) {
            fetch('/api/products?' + new URLSearchParams(queryObject))
                .then(res => res.json())
                .then(console.log);
        },
    },
);

Returns

An object with the current values and the methods below.

Methods

set(key, value)

Sets a single filter value (triggers a re-render).

filters.set('name', 'John');

toggle(key, value)

Adds or removes a value from a multiple filter — ideal for checkboxes.

filters.toggle('category', 'electronics');

bind(key)

Returns { value, onChange } props for a controlled input bound to a single filter.

<input {...filters.bind('name')} />

get()

Triggers the onApply callback with the current filter values.

toQueryObject(transformKeys = true)

Converts current values into a plain query object.

filters.toQueryObject();
// { name: 'John', category: 'electronics,furniture', price: '100,500' }

toOrderedQueryObject(transformKeys = true)

Same as toQueryObject, but preserves the parameter order from the current URL.

toSearchParams()

Returns a URLSearchParams object built from the current values.

has(filter, value)

Checks whether a filter contains a specific value.

clear(filter, shouldGet = true)

Resets one filter (or an array of filters) to its default. Calls get() afterwards if an onApply callback is set and shouldGet is true.

clearAll()

Resets all filters to their defaults.

data()

Returns the current values object.

setOptions(newOptions)

Merges new options into the current ones.

Key transformation

Use createFilterFactory with a keyTransformer to map filter keys to URL parameter names — handy for Spatie's filter[...] convention:

import { useFilters, createFilterFactory } from '@veebisepad/react-query-filters';

const factory = createFilterFactory({
    keyTransformer: key => `filter[${key}]`,
});

const filters = useFilters({
    name: factory.single<string>(), // serialized as filter[name]
    category: factory.multiple<string>(), // serialized as filter[category]
});

Example Usage

React + Inertia.js + Spatie QueryBuilder

import { useFilters, createFilterFactory } from '@veebisepad/react-query-filters';
import { router } from '@inertiajs/react';

const factory = createFilterFactory({ keyTransformer: key => `filter[${key}]` });

export default function Products() {
    const filters = useFilters(
        {
            name: factory.single<string>(),
            category: factory.multiple<string>(),
            date: factory.range<string>(),
        },
        {
            onApply(queryObject) {
                router.visit(route('products.index', queryObject), {
                    preserveScroll: true,
                    preserveState: true,
                });
            },
        },
    );

    return (
        <div>
            {/* Single value filter (text input) */}
            <label>
                Name:
                <input {...filters.bind('name')} type="text" placeholder="Enter name" />
            </label>

            {/* Multiple values filter (checkboxes) */}
            <fieldset>
                <legend>Category</legend>
                {['electronics', 'furniture', 'apparel'].map(cat => (
                    <label key={cat}>
                        <input
                            type="checkbox"
                            checked={filters.has('category', cat)}
                            onChange={() => filters.toggle('category', cat)}
                        />
                        {cat}
                    </label>
                ))}
            </fieldset>

            {/* Range filter (date range) */}
            <label>
                From:
                <input
                    type="date"
                    value={filters.values.date.from ?? ''}
                    onChange={e => filters.set('date', { ...filters.values.date, from: e.target.value })}
                />
            </label>
            <label>
                To:
                <input
                    type="date"
                    value={filters.values.date.to ?? ''}
                    onChange={e => filters.set('date', { ...filters.values.date, to: e.target.value })}
                />
            </label>

            <button onClick={() => filters.get()}>Apply Filters</button>
            <button onClick={() => filters.clearAll()}>Clear All</button>
        </div>
    );
}

License

MIT