store and retrieve state into/from the browsers location history 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 the application in a customizable state
• useLocationState(name, defaultValue)
  • restores the latest value after navigation actions (back/forward), by keeping value in history.state
  • supported value types: string | number | boolean | Date | Array | Object
  • handles complex & nested values - all values that can be serialized are supported
• useQueryState(name, defaultValue)
  • restores the latest value from URL (location.href) and after navigation actions (back/forward)
  • supported value types: string | number | boolean | Date | 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 defaultValue instead

Installation

yarn add use-location-state

Using react-router or another popular router? For the best experience install one of the router integrations.

Usage

useLocationState() and useQueryState() work similar to the useState() hook, as they also return the current value and a update function in a tuple [currentValue, updateValueFn].

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

const [commentText, setCommentText] = useLocationState('commentText', '')
const [priceMax, setPriceMax] = useQueryState('priceMax', 30)

The defaultValue works as a fallback and is returned when there is no value in the query or location state for this parameter.

The defaultValue can not be changed after the first render, so that same url always provides the same state.

useLocationState()

useLocationState() is perfect, when you want to store a state that should not be reflected in the URL or in case of a complex data structure like a nested object/array.

const [commentText, setCommentText] = useLocationState('commentText', '')

The name you pass, in this case 'commentText', will be used as a key when storing the value. So when you use the same name (and default value) in another component, you will get the same state.

setCommentText('Wow, this works like a charm!')

The updated state will be restored when the pages reloads and after the user navigated to a new page and comes back using a back/forward action.

useQueryState()

useQueryState() is a great, when you want to store information about the current state of you app in the URL.

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

The name you pass will be used as a parameter name in the query string, when setting a new value:

setValue('different value')

After calling the update function setValue() 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) or by loading the same URL anywhere else.

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 object 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:

Next.js

Import from use-location-state/next to use the router build into Next.js, which enables you to use the query state also during SSR.

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

export { getServerSideProps } from 'use-location-state/next' // [1]

export default function Page() {
  const [count, setCount] = useQueryState('count', 0)
  //...
}

[1] Page must be server rendered (SRR), otherwise React warns about a hydration mismatch, when your initial rendering depends on the query state. Export your own getServerSideProps function or the provided empty one.

react-router (react-router@^6.0.0)

Install & import the package for react-router

yarn add react-router-use-location-state

import {
  useLocationState,
  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

Gatsby & @reach/router

Gatsby & Reach Router are supported. Gatsby currently always scrolls up on location (state) changes. To keep the scroll position, when you update location state using the update function of useLocationState, add these lines to the gatsby-browser.js file in gatsby root folder.

// keeps same scroll pos when history state is pushed/replaced (same location === same position)
// see: https://www.gatsbyjs.org/docs/browser-apis/#shouldUpdateScroll
exports.shouldUpdateScroll = ({ routerProps, getSavedScrollPosition }) => {
  const currentPosition = getSavedScrollPosition(routerProps.location)
  return currentPosition || true
}

More routers soon - work in progress

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

Compatibility

Tested in current versions Chrome, Firefox, Safari, Edge, and IE11. This library relies on new, yet stable ECMAScript features, so you might need to include a polyfill if you want to support older browsers like IE11:

import 'react-app-polyfill/ie11'
import 'react-app-polyfill/stable'