!GitHub top language

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

``bash
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.

`javascript
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.

$3

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.

`javascript
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.

`javascript
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.

$3

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

`javascript
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:

`javascript
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.

$3

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'.

`javascript
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).

$3

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

function MyComponent() {
const [active, setActive] = useQueryState('active', true)
return (


`javascript
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:

$3

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.

`javascript
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.

$3

Install & import the package for react-router

`bash
yarn add react-router-use-location-state
`

`javascript
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
`

$3

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.

`javascript
// 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
}
`

$3

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:

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