Library / SDK
pmndrs/valtio avatar
pmndrs/valtio

Valtio runs two proxies under every render, and only one of them watches reads

🧙 Valtio makes proxy-state simple for React and Vanilla

10,245 stars294 forksTypeScriptMIT

At a glance

What is it?
Valtio is an MIT proxy-state library for React and vanilla JavaScript, published as a single package. The model is small, but the interesting parts are the edges: frozen snapshots break methods that use this, batching needs a per-component switch for inputs, ref untracks globally, and the Suspense path ships with a documented de-optimization.
Who is it for?
Use Valtio when you want plain object mutation with React rendering driven by what a component actually reads, and when you can live with reading the source outside render. Check three things first: whether your team can follow the read-inside-render rule, whether you need an input field and therefore the synchronous path, and whether you can accept the React 19 data path with its useTransition problem and a third-party remedy.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 16 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pmndrs/valtio10,245 ★ · +7
Star history
Repository2026-09-222026-11-15
pmndrs/valtio10.2k10.2k

7 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A proxy for writes and a second proxy for reads

Valtio installs as one package, and the first thing you do with it is hand it an object, which comes back as a self-aware proxy you can mutate with ordinary JavaScript syntax.

bash
npm install valtio
jsx
import { proxy, useSnapshot } from 'valtio'

const state = proxy({ count: 0, text: 'hello' })

Underneath that surface, every render runs two proxies with different jobs. proxy() from valtio/vanilla records writes, the mutation or write tracking half. The snapshot you get back is wrapped again by createProxy() from proxy-compare, which records reads so the component learns which properties were touched. That second layer is why a component re-renders only when the parts of state it accesses have changed, and why useSnapshot hands back a new proxy each time rather than one shared frozen object. The read set is decided by whatever your render function happens to touch, so reading snap.obj.foo also subscribes you to foo. The rule of thumb is to read snapshots inside render and read the source everywhere else.

Snapshots are frozen, so methods that lean on this go quiet

A proxy holding a count and an inc method that does ++this.count works when you call state.inc(), because this points at state. The same call on a snapshot does not work, because this points at the snapshot and the snapshot is frozen, so it does not work. The project's own answer is to stop using this and bind through an arrow function that closes over state, and the section covering this is marked as material for expert users. For a reader the failure mode arrives late. The state object looks correct, the mutating method works everywhere except the one place a component reads through a snapshot, and the write simply never happens. eslint-plugin-valtio is suggested for anyone new to the library, which is a fair signal that this pattern is easy to get wrong before you know to look for it.

TypeScript below 4.5 receives a file named after the requirement

The package manifest gives TypeScript a special deal, and part of that deal is a stub. The exports map points import consumers at esm/index.mjs with types from esm/index.d.mts, while the default and react-native conditions point at index.js with index.d.ts. The typesVersions field then splits by compiler version: anything on TypeScript 4.5 or above receives the real declaration files, while older compilers are handed ts_version_4.5_and_above_is_required.d.ts for both the root entry and the esm paths. A pre-4.5 project therefore gets a file whose name states the requirement rather than a type error explaining it. Separately, the snap variable is typed as a deeply read-only object, and the documented escape is to loosen useSnapshot so it returns T directly when that readonly attribute gets in the way, tracked as issue #327.

Mutations batch by default, and inputs need the switch flipped

State mutations are batched before they trigger a re-render, and there is one documented way to turn that off. Passing a second argument to useSnapshot with sync: true skips the batching, and the named use case is an input element, tracked as issue #270. The default batching is what collapses a burst of writes into a single render. The consequence for anyone wiring a text field is that the two access paths are not interchangeable, and turning sync on costs the batching that the rest of the application depends on. The TextBox pattern reads snap.text to render the value and writes state.text in onChange, and that pair only holds together because sync is enabled for that component.

Four granularities of change tracking, each bound to a different shape

subscribe(state, callback) fires for every change and returns an unsubscribe function you call to stop listening. Passing a nested proxy such as state.obj or state.arr narrows it to that slice, so pushing to an array no longer wakes a subscriber watching an unrelated object. A primitive leaf has no proxy to hand over, which is why subscribeKey in valtio/utils takes a key name plus the new value instead. watch in the same module is the pull style variant: the callback receives a get function and auto-subscribes to whatever it reads inside, so the subscription list is derived from the code rather than declared in advance. subscribeKey(state, 'count', callback) is the shape for a single counter. The practical advice is to pick the narrowest one that works, because the wide subscription is the one that turns a localized write into a broad render.

ref untracks globally, and later composition inherits that

ref exists for objects that belong inside state but should not be watched, such as a DOM node or a large nested structure full of accessors. Passed an existing Valtio proxy it does something stronger than skipping one property: it returns the same proxy and marks it globally untracked, including in later proxy composition. That is the detail that changes how you reach for it. The object keeps its identity, and any proxy built on top of it inherits the untracked status, so the escape is permanent rather than scoped to the call site. The API page at docs/api/advanced/ref.mdx is the reference for that behaviour, and issues #61 and #178 are cited as the background. If you ref something by mistake and later expect writes to it to trigger renders, nothing inside the state model will warn you that the tracking was turned off for good.

The Suspense path works and de-optimizes at the same time

Data fetching is handled by putting a promise in the proxy, reading it from a snapshot with the React use hook, and letting the parent own the Suspense fallback and the error handling, which removes the async back-and-forth from inside the component. React 19 supplies use directly, and React 18 users are pointed at react18-use for the same shape. Underneath that convenience sits a problem the project states rather than hides: the approach still suffers from a de-optimization that prevents useTransition from working well. The hook you would reach for when data loads quietly does not behave the way you expect. The stated mitigation is not part of the package at all but a third-party library, use-valtio, which means the fix for a known flaw lives outside the code you installed.

Six Rollup configurations and a four step postbuild

Publishing Valtio is not one Rollup pass. The build script runs a prebuild step that removes dist, then fans out across six named configurations, build:base, build:utils, build:vanilla, build:vanilla_utils, build:react, and build:react_utils, each calling rollup -c with its own flag. A postbuild then runs four further steps in order, patch-d-ts, copy, patch-old-ts, and patch-esm, so the declaration files are rewritten after bundling rather than emitted by it. build-watch reruns the same six configurations with --watch. Inside the repository, tests run through vitest.config.mts alongside a tests directory, and pnpm-lock.yaml with pnpm-workspace.yaml make pnpm the expected package manager, even though the line a consumer sees is the single npm install valtio.

Editorial conclusion

Use Valtio when you want plain object mutation with React rendering driven by what a component actually reads, and when you can live with reading the source outside render. Check three things first: whether your team can follow the read-inside-render rule, whether you need an input field and therefore the synchronous path, and whether you can accept the React 19 data path with its useTransition problem and a third-party remedy.

Frequently asked questions

What is Valtio?

Valtio is an MIT proxy-state library for React and vanilla JavaScript. You pass an object to proxy() to get a self-aware proxy, mutate it like a normal JavaScript object from anywhere, and read it in React through useSnapshot.

What is the difference between Valtio and Jotai?

The README describes its own model: proxy() handles mutation tracking, useSnapshot returns a read-only snapshot for rendering, and subscribe, subscribeKey, or watch handle change tracking outside components.

What is the difference between Valtio and Redux?

In the README, mutations are plain assignments and method calls. The only documented link is inspection, since devtools from valtio/utils connects a proxy to the Redux DevTools Extension for plain objects and arrays.

Is Valtio faster than Zustand on performance?

The README's performance claim is about render granularity: a component re-renders only when the parts of state it accesses have changed, and subscribe, subscribeKey, or watch narrow notifications to a slice of state.

How does Valtio differ from Immer?

The README documents two proxies with separate jobs, with proxy() from valtio/vanilla for write tracking and createProxy() from proxy-compare for read tracking.

Official sources

  1. License: MIT
  2. pmndrs/valtio on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pmndrs-valtio.svg)](https://hysenlabs.com/projects/pmndrs-valtio)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pmndrs-valtio.svg)](https://hysenlabs.com/projects/pmndrs-valtio)

Was this useful?