Introduction

This page describes what persistent-state does, who it is for, how stable it is and where to go next.

What is persistent-state?

persistent-state is a small library that keeps a piece of React state in the browser’s storage and restores it on the next visit. You declare each key once with persistentState(), choosing where it lives: a cookie, localStorage or sessionStorage. You then read and write it in components with useStoredState().

Cookies are the one storage a server can read. With the Next.js entry point, a Server Component reads the cookie values of the request, so the first render already matches what the visitor stored, without a flash of default state.

Who is it for?

persistent-state is for React and Next.js applications that remember small preferences, such as a theme, a layout or a dismissed notice, and want them to survive reloads, stay in sync across tabs and, for cookies, render correctly on the server. It is not a global state manager and not a replacement for a database.

How to use the docs

The docs are organized into the following sections:

Getting started: Requirements, installation and a first stored value.
Guides: Task-oriented pages, such as choosing a storage, using persistent-state with Next.js, schemas and migrations, and consent.
API reference: Every export, option and type.
How it works: The internals.
Help: Migrating from 0.2, a comparison with other libraries, the roadmap and the changelog.

Use the sidebar to navigate between sections, or search with Ctrl+K or Cmd+K.

For AI assistants and coding agents, the docs are also published as plain Markdown: /llms.txt lists them and /llms-full.txt holds every page.