# url-state-hook

> This is a React hook that is very similar to the built-in `React.useState()`, except that it mirrors the current state in the url as a query parameter. When a component that is using this hook mounts, if the url already contains a query-parameter value fo

Latest version **1.2.3** (published 2020-01-21) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install url-state-hook
pnpm add url-state-hook
yarn add url-state-hook
bun add url-state-hook
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.2.3 |
| Published | 2020-01-21 |
| First published | 2020-01-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=8 |
| Dependencies | 2 |
| Unpacked size | 620.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | williammetcalf |
| Maintainers | williammetcalf |

## Links

- npm: https://www.npmjs.com/package/url-state-hook
- Repository: https://github.com/williammetcalf/url-state-hook
- npm.io page: https://npm.io/package/url-state-hook

## Dependencies (2)

- [lodash.isequal](https://npm.io/package/lodash.isequal.md) ^4.5.0
- [lodash.debounce](https://npm.io/package/lodash.debounce.md) ^4.0.8

## Recent versions

- 1.2.3 (latest) — 2020-01-21
- 1.2.2 — 2020-01-20
- 1.2.1 — 2020-01-20
- 1.2.0 — 2020-01-20
- 1.1.0 — 2020-01-20
- 1.0.10 — 2020-01-17
- 1.0.9 — 2020-01-17
- 1.0.8 — 2020-01-17
- 1.0.7 — 2020-01-17
- 1.0.6 — 2020-01-17
- 1.0.5 — 2020-01-17
- 1.0.4 — 2020-01-17
- 1.0.2 — 2020-01-16
- 1.0.1 — 2020-01-16
- 1.0.0 — 2020-01-16

## README

# url-state-hook

This is a React hook that is very similar to the built-in `React.useState()`, except that it mirrors the current state in the url as a query parameter. When a component that is using this hook mounts, if the url already contains a query-parameter value for the hook, it will use that as the initial state.

This allows page state to be maintained over various sessions, page refreshes, or back button navigation.

By default this hook it set up to use the default React Router from `react-router-dom`, but it can be configured to use other routers as well.

### This is not a global state management hook

## Install

#### NPM

```bash
npm install --save url-state-hook
```

#### Yarn

```bash
yarn add url-state-hook
```

## Live Demo

https://williammetcalf.github.io/url-state-hook/

## Basic Usage

```tsx
import useUrlState from "url-state-hook";

const Example = () => {
  const [value, setValue] = useUrlState("s", "default value");

  return (
    <div>
      <input value={value} onChange={e => setValue(e.target.value)} />
    </div>
  );
};
```

## Basic Array Usage

This package also exports a `useUrlArrayState` to handle array states. This is really just a wrapper around the default `useUrlState` with a customized `decode` option to handle deserializing the array.

```tsx
import { useUrlArrayState } from "./use-state-hook";

const Example = () => {
  const [arrayState, setArrayState] = useUrlArrayState("arr", []);

  return (
    <div>
      <ul>
        {arrayState.map((val, idx) => (
          <li key={idx}>
            {val}
            <button
              onClick={() => {
                const newState = [...arrayState];
                newState.splice(idx, 1);
                setArrayState(newState);
              }}
            >
              x
            </button>
          </li>
        ))}
      </ul>
      <input
        onKeyPress={e => {
          if (e.key === "Enter") {
            const newState = [...arrayState];
            newState.push(e.target.value);
            e.target.value = "";
            setArrayState(newState);
          }
        }}
      />
    </div>
  );
};
```

## Nextjs Example

By default `useUrlState` uses the built in React Router, but by configuring the `options` parameter other routers can be used instead. To do this, you must set the `options.useCurrentUrlHook` and `options.updateUrlFn` values. For example, here is a wrapper that can be used to make `useUrlState` work with Nextjs.

`use-next-js-url-state.ts`

```ts
import Router, { useRouter } from "next/router";
import useUrlState, { Options } from "url-state-hook";

function useNextjsUrlState<T>(
  key: string,
  defaultValue: T,
  options?: Omit<Options<T>, "useCurrentUrlHook" | "updateUrlFn">
) {
  const { route, pathname } = useRouter();
  const opts: Options<T> = {
    ...options,
    useCurrentUrlHook: () => {
      const { asPath } = useRouter();
      return asPath;
    },
    updateUrlFn: (searchString: string) => {
      typeof window === "undefined"
        ? () => {}
        : Router.replace(route, `${pathname}${searchString}`, {
            shallow: true
          });
    }
  };

  return useUrlState(key, defaultValue, opts);
}

export default useNextjsUrlState;
```

`example.tsx`

```tsx
import React from "react";
import useNextjsUrlState from "./use-next-js-url-state";

const Example: FC = () => {
  const [value, setValue] = useNextjsUrlState("s", "default value");

  return (
    <div>
      <input value={value} onChange={e => setValue(e.target.value)} />
    </div>
  );
};
```

## Api

### Hook Parameters

| param          | description                                                                          | required? |
| -------------- | ------------------------------------------------------------------------------------ | --------- |
| _key_          | url query-param name used when storing the state in the url                          | yes       |
| _defaultValue_ | default state value used when a initial value _cannot_ be taken from the current url | yes       |
| _options_      | `Options` object                                                                     | no        |

### Options

| key                 | description                                                                                                                                                                                                                                            | default value                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
| _decode_            | function that deserializes the value stored in the url. Out of the box this hook will work with strings and numbers, but if a object or array is used as the state value, you need to supply a function to deserialize a string into the expected type |                                       |
| _useCurrentUrlHook_ | a function or React hook that returns the current url                                                                                                                                                                                                  | `ReactRouterDom.useLocation()`        |
| _updateUrlFn_       | a function that can be used to update the current url                                                                                                                                                                                                  | `ReactRouterDom.useHistory().replace` |
| _urlUpdateDebouce_  | a time in MS to debounce the updating of the url, this is necessary to prevent race conditions where multiple `useUrlState()` hooks update their state at the same time                                                                                | `500`                                 |

## License

MIT © [williammetcalf](https://github.com/williammetcalf)

---

This hook is created using [create-react-hook](https://github.com/hermanya/create-react-hook).

---
_Source: https://npm.io/package/url-state-hook · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._