Sharing is caring!

React Hook for managing state in URL query parameters with easy serialization. 


React Hook for managing state in URL query parameters with easy serialization.

Works with React Router and Reach Router out of the box. TypeScript supported.

npm Travis (.com)

Installation | Usage | Examples | API | Demo

When creating apps with easily shareable URLs, you often want to encode state as query parameters, but all query parameters must be encoded as strings. useQueryParams allows you to easily encode and decode data of any type as query parameters with smart memoization to prevent creating unnecessary duplicate objects. It uses serialize-query-params.

Not ready for hooks? Check out react-url-query for a higher-order component (HOC) approach.


Using npm:

$ npm install --save use-query-params

Link your routing system (e.g., React Router exampleReach Router example):

import React from 'react';
import ReactDOM from 'react-dom';
import { BrowserRouter as Router, Route } from 'react-router-dom';
import { QueryParamProvider } from 'use-query-params';
import App from './App';

    <queryparamprovider reactrouterroute="{Route}">


Add the hook to your component. There are two options: useQueryParam:

import * as React from 'react';
import { useQueryParam, NumberParam, StringParam } from 'use-query-params';

const UseQueryParamExample = () =&gt; {
  // something like: ?x=123&amp;foo=bar in the URL
  const [num, setNum] = useQueryParam('x', NumberParam);
  const [foo, setFoo] = useQueryParam('foo', StringParam);

  return (


<h1>num is {num}</h1>

      <button onclick="{()" ==""> setNum(Math.random())}&gt;Change</button>

<h1>foo is {foo}</h1>

      <button onclick="{()" ==""> setFoo(`str${Math.random()}`)}&gt;Change</button>


export default UseQueryParamExample;

Or useQueryParams:

import * as React from 'react';
import {
} from 'use-query-params';

const UseQueryParamsExample = () =&gt; {
  // something like: ?x=123&amp;q=foo&amp;filters=a&amp;filters=b&amp;filters=c in the URL
  const [query, setQuery] = useQueryParams({
    x: NumberParam,
    q: StringParam,
    filters: ArrayParam,
  const { x: num, q: searchQuery, filters = [] } = query;

  return (


<h1>num is {num}</h1>

      <button onclick="{()" ==""> setQuery({ x: Math.random() })}&gt;Change</button>

<h1>searchQuery is {searchQuery}</h1>

<h1>There are {filters.length} filters active.</h1>

      <button onclick="{()" =="">
            { x: Math.random(), filters: [...filters, 'foo'], q: 'bar' },
        Change All


export default UseQueryParamsExample;

Subscribe to the Newsletter

Get our latest news,tutorials,guides,tips & deals delivered to your inbox.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.