Valtio

Definition

Valtio is a proxy-based state management library for JavaScript and React that lets developers mutate a plain state object directly while automatically tracking which parts of that object are read by components, so only the components actually depending on a changed value re-render. It offers a mutable programming model on top of an internally immutable, snapshot-based mechanism, aiming to combine the simplicity of direct mutation with efficient, fine-grained reactivity.

Overview

Valtio was created to give developers a way to write state updates as ordinary, direct mutations, such as assigning to a property on an object, while still getting the render-optimization benefits that immutable state libraries typically require careful selector design to achieve. It targets the common frustration of immutable-update boilerplate in tools like Redux or plain useState with object state, where updating one nested field requires spreading every ancestor object. Mechanically, Valtio's proxy function wraps a plain JavaScript object in a Proxy that intercepts property reads and writes. Writes are applied to the underlying object directly, but Valtio internally derives an immutable snapshot of the state via its snapshot function whenever a mutation occurs, which is what React's useSnapshot hook actually subscribes to. useSnapshot uses the proxy's read-tracking mechanism to know precisely which properties a component accessed during render, so it can skip re-rendering that component if a later mutation touches a property the component never read, delivering automatic fine-grained reactivity without manual memoized selectors. Valtio differs from Immer, which produces a new immutable object from a draft but requires state itself to remain immutable at rest between updates, whereas Valtio's proxy state remains genuinely mutable and can be mutated from anywhere in the codebase, including outside of React entirely, such as inside plain utility functions or async handlers. Compared to Zustand, which follows an immutable, selector-based subscription model similar to Redux at a smaller scale, Valtio takes the opposite philosophical stance by embracing mutation directly, appealing to developers who find spread-based immutable updates unnatural for deeply nested state. In practice, Valtio is used in React applications, often games, editors, or dashboards with complex, deeply nested state, where fine-grained reactivity without manual selectors saves substantial code compared to Redux-style patterns, and in non-React JavaScript code where a mutable but reactive object model is convenient, such as syncing state to external systems or WebSocket-driven interfaces. The main trade-off with Valtio is that the illusion of true, uncontrolled mutability can make it harder to reason about where and when state changes across a large codebase, since any code holding a reference to the proxy can mutate it, unlike architectures that funnel all changes through a single reducer or action-dispatch mechanism. This can complicate debugging and testing in large teams unless mutation sites are kept disciplined and centralized by convention, since the library itself enforces no boundaries around where state changes are permitted to originate.

Key Features

• Lets developers mutate state objects directly via a JavaScript Proxy
• Automatically tracks which properties each component reads
• Re-renders only components whose read properties actually changed
• Provides a useSnapshot hook for React components to subscribe to state
• Derives immutable snapshots internally from mutable proxy state
• Can be mutated from outside React, including plain utility functions
• Requires no manual selectors or memoization for fine-grained updates

Use Cases

Alternatives

Frequently Asked Questions

Related in Web