0
# Valtio
1

2
Valtio makes proxy-state simple for React and vanilla JavaScript applications. It creates self-aware proxy objects that automatically track mutations and trigger re-renders only when accessed parts of the state change, offering maximum simplicity and performance with minimal boilerplate.
3

4
## Package Information
5

6
- **Package Name**: valtio
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install valtio`
10

11
## Core Imports
12

13
```typescript
14
import { proxy, useSnapshot } from "valtio";
15
```
16

17
For vanilla JavaScript or utilities:
18

19
```typescript
20
import { proxy, snapshot, subscribe, ref, getVersion } from "valtio";
21
import { watch, subscribeKey, devtools, deepClone, proxySet, proxyMap, isProxySet, isProxyMap } from "valtio/utils";
22
```
23

24
CommonJS:
25

26
```javascript
27
const { proxy, useSnapshot } = require("valtio");
28
const { watch, subscribeKey, devtools, deepClone, proxySet, proxyMap } = require("valtio/utils");
29
```
30

31
## Basic Usage
32

33
```typescript
34
import { proxy, useSnapshot } from "valtio";
35

36
// Create reactive state
37
const state = proxy({ count: 0, text: "hello" });
38

39
// React component with automatic re-renders
40
function Counter() {
41
  const snap = useSnapshot(state);
42
  return (
43
    <div>
44
      {snap.count}
45
      <button onClick={() => ++state.count}>+1</button>
46
    </div>
47
  );
48
}
49

50
// Vanilla JavaScript with subscriptions
51
import { snapshot, subscribe } from "valtio";
52

53
const unsubscribe = subscribe(state, () => {
54
  console.log("State changed:", snapshot(state));
55
});
56
```
57

58
## Architecture
59

60
Valtio is built around several key components:
61

62
- **Proxy Core**: Self-tracking proxy objects that detect mutations without explicit state setters
63
- **Snapshot System**: Immutable snapshots for safe reading in React components and other contexts
64
- **Subscription Engine**: Fine-grained change detection and notification system
65
- **React Integration**: Optimized hooks that only re-render when accessed properties change
66
- **Utility Library**: Additional tools for advanced use cases like reactive effects, DevTools integration, and collection handling
67

68
## Capabilities
69

70
### Core Proxy System
71

72
Foundation of Valtio's reactivity providing proxy creation, immutable snapshots, and change subscriptions. Essential for all state management scenarios.
73

74
```typescript { .api }
75
function proxy<T extends object>(baseObject?: T): T;
76
function snapshot<T extends object>(proxyObject: T): Snapshot<T>;
77
function subscribe<T extends object>(
78
  proxyObject: T,
79
  callback: (unstable_ops: Op[]) => void,
80
  notifyInSync?: boolean
81
): () => void;
82
```
83

84
[Core Proxy System](./core-proxy.md)
85

86
### React Integration
87

88
React hooks optimized for Valtio's proxy system, providing automatic re-rendering and ergonomic state access patterns.
89

90
```typescript { .api }
91
function useSnapshot<T extends object>(
92
  proxyObject: T,
93
  options?: { sync?: boolean }
94
): Snapshot<T>;
95

96
function useProxy<T extends object>(proxy: T): T;
97
```
98

99
[React Integration](./react-integration.md)
100

101
### Advanced Utilities
102

103
Extended functionality including reactive effects, key-specific subscriptions, DevTools integration, deep cloning, and specialized collections.
104

105
```typescript { .api }
106
function watch(
107
  callback: (get: <T extends object>(proxyObject: T) => T) => void | (() => void) | Promise<void | (() => void)>,
108
  options?: { sync?: boolean }
109
): () => void;
110

111
function subscribeKey<T extends object, K extends keyof T>(
112
  proxyObject: T,
113
  key: K,
114
  callback: (value: T[K]) => void,
115
  notifyInSync?: boolean
116
): () => void;
117

118
function devtools<T extends object>(
119
  proxyObject: T,
120
  options?: { enabled?: boolean; name?: string }
121
): (() => void) | undefined;
122
```
123

124
[Advanced Utilities](./utilities.md)
125

126
## Types
127

128
```typescript { .api }
129
type Snapshot<T> = T extends { $$valtioSnapshot: infer S }
130
  ? S
131
  : T extends SnapshotIgnore
132
    ? T
133
    : T extends object
134
      ? { readonly [K in keyof T]: Snapshot<T[K]> }
135
      : T;
136

137
type Op =
138
  | [op: 'set', path: (string | symbol)[], value: unknown, prevValue: unknown]
139
  | [op: 'delete', path: (string | symbol)[], prevValue: unknown];
140
```