0
# Jotai
1

2
Jotai is a primitive and flexible state management library for React applications that scales from simple useState replacements to enterprise TypeScript applications. It provides atom-based state management without string keys, featuring a minimal 2kb core API with extensive utilities and extensions.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { atom, useAtom, useAtomValue, useSetAtom, Provider } from "jotai";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { atom, useAtom, useAtomValue, useSetAtom, Provider } = require("jotai");
21
```
22

23
Utility imports:
24

25
```typescript
26
import { atomWithStorage, atomWithReset, loadable, RESET } from "jotai/utils";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { atom, useAtom, useAtomValue, useSetAtom } from "jotai";
33

34
// Create atoms
35
const countAtom = atom(0);
36
const doubleCountAtom = atom((get) => get(countAtom) * 2);
37
const incrementAtom = atom(null, (get, set) => {
38
  set(countAtom, get(countAtom) + 1);
39
});
40

41
// Use in React components
42
function Counter() {
43
  const [count, setCount] = useAtom(countAtom);
44
  const doubleCount = useAtomValue(doubleCountAtom);
45
  const increment = useSetAtom(incrementAtom);
46

47
  return (
48
    <div>
49
      <p>Count: {count}</p>
50
      <p>Double: {doubleCount}</p>
51
      <button onClick={() => setCount(count + 1)}>Increment Count</button>
52
      <button onClick={increment}>Increment via Action</button>
53
    </div>
54
  );
55
}
56
```
57

58
## Architecture
59

60
Jotai is built around several key concepts:
61

62
- **Atoms**: The fundamental unit of state, representing a piece of state or a derived value
63
- **Store**: Container for atom values with subscription capabilities
64
- **Provider**: React context provider for scoped stores
65
- **Hooks**: React integration for reading and writing atom values
66
- **Utilities**: Extended functionality for common patterns (storage, reset, async, etc.)
67

68
## Capabilities
69

70
### Core Atoms
71

72
Basic atom creation and type definitions for building reactive state.
73

74
```typescript { .api }
75
function atom<Value>(initialValue: Value): PrimitiveAtom<Value>;
76
function atom<Value>(read: Read<Value>): Atom<Value>;
77
function atom<Value, Args extends unknown[], Result>(
78
  read: Read<Value>,
79
  write: Write<Args, Result>
80
): WritableAtom<Value, Args, Result>;
81

82
interface Atom<Value> {
83
  toString: () => string;
84
  read: Read<Value>;
85
  debugLabel?: string;
86
}
87

88
interface WritableAtom<Value, Args extends unknown[], Result> extends Atom<Value> {
89
  write: Write<Args, Result>;
90
  onMount?: OnMount<Args, Result>;
91
}
92

93
type PrimitiveAtom<Value> = WritableAtom<Value, [SetStateAction<Value>], void>;
94
```
95

96
[Core Atoms](./core-atoms.md)
97

98
### React Integration
99

100
React hooks and components for integrating atoms with React applications.
101

102
```typescript { .api }
103
function useAtom<Value, Args extends unknown[], Result>(
104
  atom: WritableAtom<Value, Args, Result>,
105
  options?: Options
106
): [Awaited<Value>, SetAtom<Args, Result>];
107

108
function useAtomValue<Value>(
109
  atom: Atom<Value>,
110
  options?: Options
111
): Awaited<Value>;
112

113
function useSetAtom<Value, Args extends unknown[], Result>(
114
  atom: WritableAtom<Value, Args, Result>,
115
  options?: Options
116
): SetAtom<Args, Result>;
117

118
function Provider(props: {
119
  children?: ReactNode;
120
  store?: Store;
121
}): ReactElement;
122
```
123

124
[React Integration](./react-integration.md)
125

126
### Vanilla Utilities
127

128
Core utility functions for advanced atom patterns and functionality.
129

130
```typescript { .api }
131
const RESET: unique symbol;
132

133
function atomWithReset<Value>(
134
  initialValue: Value
135
): WritableAtom<Value, [SetStateAction<Value> | typeof RESET], void>;
136

137
function atomFamily<Param, AtomType>(
138
  initializeAtom: (param: Param) => AtomType,
139
  areEqual?: (a: Param, b: Param) => boolean
140
): AtomFamily<Param, AtomType>;
141

142
function atomWithStorage<Value>(
143
  key: string,
144
  initialValue: Value,
145
  storage?: SyncStorage<Value> | AsyncStorage<Value>
146
): WritableAtom<Value, [SetStateAction<Value>], void>;
147

148
function loadable<Value>(anAtom: Atom<Value>): Atom<Loadable<Value>>;
149
```
150

151
[Vanilla Utilities](./vanilla-utilities.md)
152

153
### React Utilities
154

155
React-specific utility hooks for advanced patterns and functionality.
156

157
```typescript { .api }
158
function useResetAtom<T>(
159
  anAtom: WritableAtom<unknown, [typeof RESET], T>,
160
  options?: Options
161
): () => T;
162

163
function useAtomCallback<Result, Args extends unknown[]>(
164
  callback: (get: Getter, set: Setter, ...args: Args) => Result,
165
  options?: Options
166
): (...args: Args) => Result;
167

168
function useHydrateAtoms<Values extends readonly (readonly [Atom<unknown>, unknown])[]>(
169
  values: Values,
170
  options?: Options
171
): void;
172
```
173

174
[React Utilities](./react-utilities.md)
175

176
## Types and Interfaces
177

178
### Core Types
179

180
```typescript { .api }
181
type Getter = <Value>(atom: Atom<Value>) => Value;
182

183
type Setter = <Value, Args extends unknown[], Result>(
184
  atom: WritableAtom<Value, Args, Result>,
185
  ...args: Args
186
) => Result;
187

188
type SetStateAction<Value> = Value | ((prev: Value) => Value);
189

190
type ExtractAtomValue<AtomType> = AtomType extends Atom<infer Value> ? Value : never;
191

192
type ExtractAtomArgs<AtomType> = AtomType extends WritableAtom<any, infer Args, any> ? Args : never;
193

194
type ExtractAtomResult<AtomType> = AtomType extends WritableAtom<any, any, infer Result> ? Result : never;
195
```
196

197
### Store Types
198

199
```typescript { .api }
200
interface Store {
201
  get: <Value>(atom: Atom<Value>) => Value;
202
  set: <Value, Args extends unknown[], Result>(
203
    atom: WritableAtom<Value, Args, Result>,
204
    ...args: Args
205
  ) => Result;
206
  sub: (atom: AnyAtom, listener: Listener) => Unsubscribe;
207
}
208

209
function createStore(): Store;
210
function getDefaultStore(): Store;
211
```
212

213
### Storage Types
214

215
```typescript { .api }
216
interface SyncStorage<Value> {
217
  getItem: (key: string, initialValue: Value) => Value;
218
  setItem: (key: string, value: Value) => void;
219
  removeItem: (key: string) => void;
220
}
221

222
interface AsyncStorage<Value> {
223
  getItem: (key: string, initialValue: Value) => Promise<Value>;
224
  setItem: (key: string, value: Value) => Promise<void>;
225
  removeItem: (key: string) => Promise<void>;
226
}
227

228
type Loadable<Value> =
229
  | { state: "loading" }
230
  | { state: "hasError"; error: unknown }
231
  | { state: "hasData"; data: Value };
232
```