query-history

A history with additional APIs to more easily manage query parameters using query-string.

This library was created for React Router v5. The latest version of React Router, v6, includes more robust query parameter support via useSearchParams. If you are using v6 we encourage you to use useSearchParams instead of this library.

Installation

Install using npm:

npm install query-history

or yarn:

yarn add query-history

Table of Contents

• Guides
  • Getting Started
  • Reading Query Parameters
  • Updating Query Parameters
  • Removing Query Parameters
  • Configuring the Query Parameter Behavior
• Acknowledgements

Guides

The following guides assume that you're using query-history with React Router.

Getting Started

Create a history object using the default export from this library, createQueryHistory.

import createQueryHistory from 'query-history';

const history = createQueryHistory();

createQueryHistory accepts all of the same option as history, so you can, for example, specify a basename option:

const history = createQueryHistory({
  basename: '/my-app',
});

For more information on the available options, refer to the history docs.

Once you have a history, you can then pass it into a Router from React Router.

import { Router } from 'react-router-dom';

// Later, in a component...
return (
  <Router history={history}>
    <App />
  </Router>
);

Reading query parameters

When using this library, the location object includes a new key, query. This is an object that represents the query parameters.

import { useLocation } from 'react-router-dom';

export default function MyComponent() {
  const { query } = useLocation();

  console.log('What is the current query?', query);

  return null;
}

For instance, given the URL https://app.com/?hello=true&sandwiches=tasty&size=40, the value of history.query would be:

{
  hello: 'true',
  sandwiches: 'tasty',
  size: '40'
}

Keep in mind that although this library will parse your query string as an object, by default the individual query string values are always strings. Notice how the size parameter is parsed as the string "40" in the example above.

You are either responsible for converting the values to their correct type in your application, or you can configure query-string to do it for you.

Updating query parameters

The history methods push and replace have been updated with improved support for updating query parameters. Additionally, a new method, updateQuery, has been introduced.

Use updateQuery to change the query parameters without redirecting to a new path.

import { useHistory } from 'react-router-dom';

export default function MyComponent() {
  const history = useHistory();

  function navigate() {
    history.updateQuery({
      sandwiches: 'tasty',
    });
  }

  return null;
}

This will merge the new params into the old. To replace the parameters, pass a second argument, { mergeQuery: false }:

history.updateQuery(
  {
    sandwiches: 'tasty',
  },
  {
    mergeQuery: false,
  }
);

When calling push or replace, pass an optional query object to specify new query parameters.

import { useHistory } from 'react-router-dom';

export default function MyComponent() {
  const history = useHistory();

  function navigate() {
    history.push({
      pathname: '/',
      query: {
        sandwiches: 'tasty',
      },
    });
  }

  return null;
}

The new parameters that you pass are merged with the existing ones. To replace the parameters, pass mergeQuery: false to history.push or history.replace:

history.push({
  pathname: '/',
  query: {
    sandwiches: 'tasty',
  },
  mergeQuery: false,
});

Removing Query Parameters

You can remove query parameters by passing their value as undefined. For example:

// Removes "sandwiches" from the query parameter list
history.updateQuery({
  sandwiches: undefined,
});

To learn more about how falsey values are parsed, refer to the query-string docs.

Configuring query parameter behavior

This library uses the query-string library to parse and serialize query parameters. To configure this behavior, the createQueryHistory function accepts two options:

• parseOptions: an object of options passed into queryString.parse()
• stringifyOptions: an object of options passed into queryString.stringify()

Click the options name in the above list to view all of the supported options.

Example: automatically parsing numbers and booleans

By default, numbers and booleans in the query parameter are parsed as strings. You can configure this library to parse them as their correct types using the following code:

import createQueryHistory from 'query-history';

const history = createQueryHistory({
  parseOptions: {
    parseNumbers: true,
    parseBooleans: true,
  },
});

Example: configuring how arrays are serialized and parsed

Different applications have different requirements when it comes to serializing arrays, and query-string supports a number of options. In this example, we set the array format to "comma". View all of the options in the query-string docs.

import createQueryHistory from 'query-history';

const history = createQueryHistory({
  stringifyOptions: {
    arrayFormat: 'comma',
  },
  parseOptions: {
    arrayFormat: 'comma
  }
});

Acknowledgements

This library was inspired by qhistory.