Persistent storage state

Hooks for synchronizing React state with browser storage.

Toolpad provides a set of primitives that harmonize how you deal with persisting global state in the browser. Through our hooks you can synchronise React state with local storage or session storage, or in the url as a query parameter. These hooks all follow a similar philosophy: they identify their data with a unique key and support rich data types through the use of codecs.

The hook's signature intentionally resembles the React.useState hook. Where the first parameter represents the key under which to store the state in the browser, and the second parameter corresponds to the initial value. An optional third parameter can be used to configure the hook.

Local Storage

String values

The default behavior of the hook is to read and write string values. All you have to do is provide a storage key and the hook does the rest. You can provide an initial value as the second parameter. Just like the React.useState hook, you can provide an initializer function in case calculating the initial value is a heavy operation. The hook will always return null during SSR and hydration.

const [value, setValue] = useLocalStorageState('string-value', 'Initial Value');

const [value, setValue] = useLocalStorageState('string-value', 'Initial Value');

Press Enter to start editing

Open this page in another tab to see the hook in action.

important Passing null to setState results in removing the value from storage.

Rich data types

If you need to store values other than strings, you can use the codec parameter in the hook options to declare the methods used for serialization and deserialization. A codec contains a parse method and stringify method.

Basic date picker

const DAYJS_CODEC: Codec<Dayjs> = {
  parse: (dateString) => dayjs(dateString),
  stringify: (date) => date.toISOString(),
};

export default function LocalStorageStateCustom() {
  const [value, setValue] = useLocalStorageState('custom-value', null, {
    codec: DAYJS_CODEC,
  });
  // ...

const DAYJS_CODEC: Codec<Dayjs> = {
  parse: (dateString) => dayjs(dateString),
  stringify: (date) => date.toISOString(),
};

export default function LocalStorageStateCustom() {
  const [value, setValue] = useLocalStorageState('custom-value', null, {
    codec: DAYJS_CODEC,
  });
  // ...

Press Enter to start editing

Codecs make it possible to use this hook in a type safe way.

Error handling

The useLocalStorageState hook returns null when local storage is not available for some reason. Errors in the codec's parse method will always be propagated. If you want to handle parsing errors, you will have to do so in the codec.

value: null

const CODEC_JSON: Codec<unknown> = {
  parse: (value) => {
    try {
      return JSON.parse(value);
    } catch {
      return { _error: 'parse failed' };
    }
  },
  stringify: (value) => JSON.stringify(value),
};

const CODEC_JSON: Codec<unknown> = {
  parse: (value) => {
    try {
      return JSON.parse(value);
    } catch {
      return { _error: 'parse failed' };
    }
  },
  stringify: (value) => JSON.stringify(value),
};

Press Enter to start editing

Custom validation

For complex data types you can pair these hooks with a typed validation library such as zod.

const schema = z.enum(['foo', 'bar', 'baz']).default('foo');

type SchemaType = z.infer<typeof schema>;

const CODEC: Codec<SchemaType> = {
  parse: (value) => {
    try {
      return schema.parse(JSON.parse(value));
    } catch {
      return 'foo';
    }
  },
  stringify: (value) => JSON.stringify(value),
};

const schema = z.enum(['foo', 'bar', 'baz']).default('foo');

type SchemaType = z.infer<typeof schema>;

const CODEC: Codec<SchemaType> = {
  parse: (value) => {
    try {
      return schema.parse(JSON.parse(value));
    } catch {
      return 'foo';
    }
  },
  stringify: (value) => JSON.stringify(value),
};

Press Enter to start editing

Persistent storage state

Local Storage

String values

Rich data types

Error handling

Custom validation

Session Storage

Search Parameters

Hook API