react-router-use-location-state

useQueryState()

store and retrieve state into/from the browsers location state using modern hooks

✨ Features

• makes it easy to provide a nice UX to your users, by restoring part of the app state after navigation actions
• makes it easy to share application in current state
• supported value types: string | number | boolean | string[] | Date
• handles stringification and parsing from query string of for supported value types
• invalid entries from the query string are discarded and the component will receive the defaultValue instead

Installation

yarn add use-location-state

Or install one of the optional router integrations

Usage

The useQueryState() works similar to the useState() hook and returns the current value and a set function in a pair.

The important difference is that you need to pass a name before your default value for your state.

const [value, setValue] = useQueryState('itemName', 'default value')

The name you pass will be used in the query string store the state (after the state was changed).

setValue('different value')

After calling the set function with a new value, the state will be saved withing the query string of the browser, so that the new state is reproducable after reloads or history navigation (using forward / back button).

http://localhost:3000/#itemName=different+value

useQueryState() uses the browsers location.hash property by default. Check out the router integrations to use location.search instead.

Push

In cases where you want the updated state to be represented as a new entry in the history, you can pass a options argument to the set function, with the method property set to 'push'.

setValue('a pushed value', { method: 'push' })

This changes the way this state change is handled when the user navigates. When the user now clicks the Back-Button, this state gets popped and the previous state is restored (instead of eg. navigating away).

Example

import { useQueryState } from 'use-location-state'

function MyComponent() {
  const [active, setActive] = useQueryState('active', true)
  return (
    <div>
      <button type="button" onClick={() => setActive(!active)}>Toggle</button>
      {active && <p>Some active content</p>}
    </div>
  )
}

Example with multiple useQueryState hooks in one component

import { useQueryState } from 'use-location-state'

function MyComponent() {
  const [name, setName] = useQueryState('name', 'Sarah')
  const [age, setAge] = useQueryState('age', 25)
  const [active, setActive] = useQueryState('active', false)
  // ...
}

Router Integration (optional)

In case you want use location.search (after the question mark in the url) you need to use one of these extended versions of the package.

We plan to provide clean and easy-to-use integrations for all popular routers. At the moment we provide integrations for:

react-router (react-router@^5.0.0)

yarn add react-router-use-location-state

import { useQueryState } from 'react-router-use-location-state'

Usage works the same as described above, except that the URL will look like this now:

http://localhost:3000/?itemName=different+value

More routers soon - work in progress

Your favorite router is missing? Feel free to suggest a router.