Valtio is a state management library that simplifies proxy-based state handling for both React and vanilla JavaScript applications. The library is maintained by the pmndrs organization and is written in TypeScript, with its primary purpose being to make mutable state management intuitive and performant through JavaScript proxies.
The core concept of Valtio is straightforward: it wraps a JavaScript object into a self-aware proxy that can be mutated directly like a normal object, without requiring immutable update patterns or complex state management boilerplate. Developers can make changes to the state from anywhere in their application using standard JavaScript mutation syntax. For React integration, Valtio provides the useSnapshot hook, which creates a local snapshot of the state that tracks changes and triggers re-renders only when the specific parts of state accessed in the render function have changed. This approach provides render optimization by detecting property access through an internal proxy mechanism based on proxy-compare technology.
Beyond React, Valtio supports vanilla JavaScript usage, allowing developers to subscribe to state changes from anywhere in their application, including outside of components. The library includes utilities like subscribeKey for subscribing to primitive values and watch for convenient state observation.
The library offers several advanced features for different use cases. The ref utility allows developers to hold objects in state without proxy tracking, useful for large nested objects with accessors. Valtio supports transient updates for frequently occurring state changes without triggering re-renders, and developers can control whether mutations are batched or synchronous depending on their needs. The library integrates with Redux DevTools Extension for debugging and state manipulation in plain objects and arrays.
Valtio includes specialized utilities like proxySet and proxyMap that mimic native Set and Map behavior while maintaining proxy reactivity. The useProxy utility provides a convenient abstraction for beginners by returning both shallow proxy state and its snapshot together. Computed properties can be defined using object getters for advanced use cases, though the library notes that this requires careful handling of the this context.
Valtio v2 requires React 18 and up and works with various renderers including react-dom, react-native, and react-three-fiber. The library is framework-agnostic and functions in Node.js, Next.js, and other environments. The ecosystem includes eslint-plugin-valtio for linting support and community-contributed recipes covering state organization, persistence, context integration, and state composition patterns.
