react-query-filters: A Headless React Hook for URL-Synced Search, Filters, Sorting & Pagination

Every React project I've worked on eventually needs the same thing: search, filters, sorting, and pagination that survive a page refresh and can be shared through a URL.

I've found myself repeatedly writing useSearchParams and URLSearchParams boilerplate to handle this.

So I built react-query-filters — a small, headless hook for managing query state and keeping it synchronized with the URL.

const {
  state,
  setSearch,
  setFilter,
  setSort,
  setPage
} = useQueryFilters();

Your URL automatically stays in sync:

/products
    ↓
/products?search=laptop&status=active&sort=price:desc&page=2

No manual URLSearchParams juggling, and browser back/forward navigation works naturally.

Why I built it
🎯 Headless — no UI components or design system imposed
🔗 URL-synced — state survives refresh and is easily shareable
⚛️ React-friendly — simple hooks-based API
🧩 Framework-agnostic core — usable with frameworks such as Next.js
📅 Date & range filters
📦 Zero runtime dependencies
🔄 Browser history support

The goal
The goal isn't to build another UI filtering library.

It's to provide a small layer for URL query-state management while leaving the UI completely up to you.

You can use it with your existing components, whether that's your own design system, shadcn/ui, MUI, or something else.

Early project
This is still an early project — currently v1.1.0.

I'd especially love feedback on the API design.

Is the API intuitive?

Are there patterns you would handle differently?

Are there edge cases around URL state that you think the library should support?

Links
GitHub:
https://github.com/Amalmktk/react-query-filters

npm:
https://www.npmjs.com/package/react-query-filters

Install it with:

npm install react-query-filters

Thanks for checking it out! 🚀