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[]
• 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 default value instead

Installation

yarn add use-location-state

In case you use react-router, please check out the router integration segment.

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.

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>
  )
}

Try it: Example in CodeSandbox

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)
  // ...
}

Try it: Example in CodeSandbox

Router Integration

We plan to provide easy-to-use integrations for all major routers. (more routers soon - work in progress) At the moment we provide integrations for:

react-router

yarn add react-router-use-location-state

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

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