Skip to content
🆙 A React hook that serializes state into the URL query string
TypeScript JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows
src
.eslintrc
.gitignore
.npmignore
.travis.yml
LICENSE
README.md
jest.config.js
package-lock.json
package.json
tsconfig.json

README.md

useQueryString

Build Status

A React hook that serializes state into the URL query string

Installation

$ npm install use-query-string

Usage

Given a location object and a history updater function, this hook will return an array who's first element is an object representing the current URL query string. The second element in the array is a function that serializes an object into the query string and updates the former query object.

import useQueryString from '@trevorblades/use-query-string';

const [query, setQuery] = useQueryString(location, updateQuery);

The first argument passed to the hook is a Location object, and the second is a history-updating function with the following signature:

(path: string): void => {
  // update the browser history
}

Parser configuration

You can supply an optional third argument to this hook that gets passed along as options to the parser function. These allow you to do things like automatically convert values to numbers or booleans, where appropriate. See the query-string docs for all of the accepted options.

const [query, setQuery] = useQueryString(
  location,
  navigate,
  {
    parseNumbers: true,
    parseBooleans: true
  }
);

Example

In this example, you'll see a component using the query string to serialize some state about a selected color. The component uses the location object from the window, and a wrapper around

import React from 'react';
import useQueryString from '@trevorblades/use-query-string';

function updateHistory(path) {
  history.pushState(null, document.title, path);
}

function ColorPicker() {
  const [{color}, setQuery] = useQueryString(
    window.location,
    updateHistory
  );

  function handleColorChange(event) {
    setQuery({color: event.target.value});
  }

  return (
    <div>
      <p style={{color}}>Color is {color}</p>
      <select value={color} onChange={handleColorChange}>
        <option value="red">Red</option>
        <option value="blue">Blue</option>
      </select>
    </div>
  );
}

Gatsby example

If you're using Gatsby, you could pass props.location and the navigate helper function from Gatsby Link as arguments to the hook.

// pages/index.js
import React from 'react';
import useQueryString from '@trevorblades/use-query-string';
import {navigate} from 'gatsby';

function IndexPage(props) {
  const [query, setQuery] = useQueryString(
    props.location, // pages are given a location object via props
    navigate
  );

  // ...the rest of your page
}

License

MIT

You can’t perform that action at this time.