State management

Where to put state — Convex, URL, localStorage, React state, Zustand. The decision tree.

Where state lives shapes everything else. The framework: put state at the lowest layer that satisfies the requirement.

Decision tree

1. Should everyone see this state? (Multi-user, persistent.)

   Yes: Convex (mutation writes to DB; queries read).

2. Should it survive a page refresh? (Single-user, persistent.)

   Yes: localStorage (or per-user Convex row if multi-device).

3. Should it be shareable via URL? (Filters, tabs, search.)

   Yes: URL query parameters.

4. Multi-component, ephemeral?

   Yes: Zustand (or React context for tree-scoped).

5. Single component, ephemeral?

   Yes: useState / useReducer.

Examples

State	Where
List of tasks	Convex
Current user	Convex (queried via auth)
Active workspace	URL (/w/{slug}/...)
Filter selection on the task list	URL (so it survives refresh and is shareable)
Modal open/closed	useState
Sidebar collapsed	localStorage (persists across sessions)
Multi-step form draft	Zustand (or localStorage if you want survival across refresh)
Theme preference	localStorage + cookie (server-side render)

Common mistakes

Putting Convex data in Zustand

useQuery is the cache. Don’t copy results into a Zustand store; you’ll fight with stale data.

Putting filter state in component state

A user sets filters, refreshes, all gone. Use URL query params instead.

Storing transient form state in Convex

Each keystroke = a mutation = wasted credits and DB churn. Use local state; persist on submit.

Tips

For collaborative editing, every keystroke goes to Convex. That’s not waste — that’s the feature. Reactive sync makes co-editing automatic.

Use useReducer for complex local state. When useState calls multiply (5+ in a single component), a reducer simplifies.

Related

Convex queries

Server state.

Optimistic updates

Pattern for instant client feedback.

Component patterns

Where state lives in your component tree.