npm package: @mits_pl/use-inertia-filters
Description: Headless Vue 3 composable for managing filter state with Inertia.js — debounced, URL-synced, TypeScript-first.
Author: MITS Sp. z o.o.
Latest version: 1.0.2

# @mits_pl/use-inertia-filters

> Headless Vue 3 composable for managing filter state with Inertia.js — debounced, URL-synced, TypeScript-first.

[![npm version](https://img.shields.io/npm/v/@mits_pl/use-inertia-filters.svg)](https://www.npmjs.com/package/@mits_pl/use-inertia-filters)
[![license](https://img.shields.io/npm/l/@mits_pl/use-inertia-filters.svg)](./LICENSE)

Built and maintained by [MITS](https://mits.pl) — a software house specializing in Laravel + Vue + Inertia.

---

## The problem

Every Laravel + Inertia app has the same boilerplate: a list page with a search input, a status dropdown, a per-page selector. Every time you need to:

1. Keep filter state in sync with the URL query string
2. Debounce the search input so you don't hammer the server
3. Fire immediately for sort/per_page changes
4. Preserve Vue component state so the page doesn't flicker
5. Reset filters back to defaults

This composable does all of that in **one line**.

---

## Installation

```bash
npm install @mits_pl/use-inertia-filters
# or
yarn add @mits_pl/use-inertia-filters
# or
pnpm add @mits_pl/use-inertia-filters
```

**Peer dependencies:** `vue >= 3.3`, `@inertiajs/vue3 >= 1.0`

---

## Quick start

```vue
<script setup lang="ts">
import { useInertiaFilters } from '@mits_pl/use-inertia-filters'

const { filters, reset, isDirty } = useInertiaFilters({
  search: '',
  status: null,
  perPage: 15,
})
</script>

<template>
  <div>
    <input v-model="filters.search" placeholder="Search..." />

    <select v-model="filters.status">
      <option :value="null">All</option>
      <option value="active">Active</option>
      <option value="inactive">Inactive</option>
    </select>

    <select v-model="filters.perPage">
      <option :value="15">15</option>
      <option :value="25">25</option>
      <option :value="50">50</option>
    </select>

    <button v-if="isDirty()" @click="reset">Clear filters</button>
  </div>
</template>
```

That's it. Changes are debounced (300ms by default), the URL is updated, and the page re-renders with fresh data from the server.

---

## How it works

1. On mount, the composable reads the current URL query string and hydrates the filter state (with type casting based on initial values).
2. When any filter changes, a debounced `router.get()` is called with only the non-default, non-empty values in the query string — keeping the URL clean.
3. The visit uses `preserveState: true` and `replace: true` by default, so the page updates without a flicker and without polluting browser history.

---

## API

### `useInertiaFilters(initialFilters, options?)`

#### `initialFilters`

A plain object defining your filter keys and their default values. Types are inferred from the initial values and used for URL hydration casting.

```ts
useInertiaFilters({
  search: '',      // string
  status: null,    // null | string
  page: 1,         // number — cast from URL string automatically
  archived: false, // boolean — cast from URL string automatically
})
```

#### `options`

| Option | Type | Default | Description |
|---|---|---|---|
| `debounce` | `number` | `300` | Debounce delay in ms |
| `preserveState` | `boolean` | `true` | Preserve Vue component state |
| `preserveScroll` | `boolean` | `true` | Preserve scroll position |
| `replace` | `boolean` | `true` | Replace history entry (no back-button spam) |
| `debounceOnly` | `string[]` | `undefined` | Only debounce these keys; all others fire immediately |
| `onBeforeVisit` | `(filters) => boolean \| void` | — | Return `false` to cancel the visit |
| `onAfterVisit` | `(filters) => void` | — | Called after each visit |

#### Return value

| Property | Type | Description |
|---|---|---|
| `filters` | `Reactive<T>` | Reactive filters object — bind with `v-model` |
| `reset()` | `() => void` | Reset all filters to initial values |
| `resetKeys(...keys)` | `(...keys) => void` | Reset specific keys only |
| `flush()` | `() => void` | Trigger visit immediately, bypassing debounce |
| `isDirty()` | `() => boolean` | True if any filter differs from its initial value |
| `isKeyDirty(key)` | `(key) => boolean` | True if the specific key differs from initial |

---

## Real-world example with `debounceOnly`

You want the `search` field to be debounced (wait for the user to stop typing), but `perPage` and `sort` should fire instantly.

```vue
<script setup lang="ts">
import { useInertiaFilters } from '@mits_pl/use-inertia-filters'

const { filters, reset, isDirty } = useInertiaFilters(
  {
    search: '',
    status: null,
    sort: 'name',
    direction: 'asc',
    perPage: 15,
  },
  {
    debounce: 400,
    debounceOnly: ['search'], // only search is debounced
  },
)
</script>
```

---

## Laravel controller

Nothing special needed on the backend — standard Inertia pattern:

```php
public function index(Request $request): Response
{
    $users = User::query()
        ->when($request->search, fn ($q, $v) => $q->where('name', 'like', "%{$v}%"))
        ->when($request->status, fn ($q, $v) => $q->where('status', $v))
        ->orderBy($request->sort ?? 'name', $request->direction ?? 'asc')
        ->paginate($request->perPage ?? 15)
        ->withQueryString();

    return Inertia::render('Users/Index', [
        'users' => $users,
        'filters' => $request->only('search', 'status', 'sort', 'direction', 'perPage'),
    ]);
}
```

---

## Why not use an existing table package?

Packages like `inertiajs-tables-laravel-query-builder` are great but opinionated:

- Require **Spatie Laravel Query Builder** on the backend
- Require **Tailwind CSS Forms plugin**
- Bring their own table UI components

`useInertiaFilters` is **headless**. No UI, no backend requirements, no CSS. Use it with any component library — shadcn-vue, PrimeVue, Vuetify, Quasar, or plain HTML.

---

## TypeScript

Full type inference out of the box:

```ts
const { filters, isKeyDirty } = useInertiaFilters({
  search: '',
  perPage: 15,
})

filters.search  // string ✓
filters.perPage // number ✓
filters.nope    // TS error ✓

isKeyDirty('search')  // ✓
isKeyDirty('nope')    // TS error ✓
```

---

## License

MIT © [MITS Sp. z o.o.](https://mits.pl)