huytdps13400/react-native-ssl-manager / .agents/skills/react-native-mmkv
react-native-mmkv
VerifiedFast synchronous key-value storage for React Native via react-native-mmkv (Nitro-backed). Covers creating and configuring MMKV instances, reading/writing all value types (string, number, boolean, buffer), React hooks for reactive UI, value-change listeners, encryption, AsyncStorage migration, and state-management integrations (zustand, redux-persist, jotai, react-query). Also covers storage limits, multi-process mode, and the V4 upgrade from the class-based API.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
| references/create-instance.md | markdown | 4.8 KB |
| references/crud-operations.md | markdown | 3.5 KB |
| references/encryption.md | markdown | 3.3 KB |
| references/hooks.md | markdown | 5.9 KB |
| references/limits-and-gotchas.md | markdown | 4.9 KB |
| references/listeners.md | markdown | 2.2 KB |
| references/migrate-from-async-storage.md | markdown | 4.4 KB |
| references/state-management.md | markdown | 6.1 KB |
| references/upgrade-v4.md | markdown | 3.7 KB |
references/hooks.md
View on GitHub---
id: hooks
title: React hooks for MMKV
scope: react-native-mmkv
keywords: useMMKVString, useMMKVNumber, useMMKVBoolean, useMMKVBuffer, useMMKVObject, useMMKV, useMMKVListener, useMMKVKeys, hooks, reactive
---
# React hooks for MMKV
## Mental model
MMKV provides React hooks that behave like `useState` — they return `[value, setter]` tuples and automatically re-render the component when the underlying MMKV value changes. This means if one component writes to a key, every other component using a hook on that key re-renders.
All hooks accept an optional second argument: a specific MMKV instance. If omitted, they use the default instance.
## Available hooks
| Hook | Returns | Description |
|------|---------|-------------|
| `useMMKVString(key, instance?)` | `[string \| undefined, (v: string \| undefined) => void]` | Reactive string value |
| `useMMKVNumber(key, instance?)` | `[number \| undefined, (v: number \| undefined) => void]` | Reactive number value |
| `useMMKVBoolean(key, instance?)` | `[boolean \| undefined, (v: boolean \| undefined) => void]` | Reactive boolean value |
| `useMMKVBuffer(key, instance?)` | `[ArrayBuffer \| undefined, (v: ArrayBuffer \| undefined) => void]` | Reactive buffer value |
| `useMMKVObject<T>(key, instance?)` | `[T \| undefined, (v: T \| undefined) => void]` | Reactive JSON object (auto stringify/parse) |
| `useMMKV(config?)` | `MMKV` | Creates/returns an MMKV instance reactively |
| `useMMKVListener(callback, instance?)` | `void` | Fires callback on any key change |
| `useMMKVKeys(instance?)` | `string[]` | Reactive list of all keys |
All value-hook setters also accept a **functional update** (like `useState`): `setValue(prev => ...)`.
## Recipes
### Basic typed hooks
```tsx
function App() {
const [username, setUsername] = useMMKVString('user.name')
const [age, setAge] = useMMKVNumber('user.age')
const [isPremium, setIsPremium] = useMMKVBoolean('user.isPremium')
const [privateKey, setPrivateKey] = useMMKVBuffer('user.privateKey')
return <Text>{username} is {age} years old</Text>
}
```
### Functional updates
Setters accept a function of the previous value, just like `useState`:
```tsx
const [age, setAge] = useMMKVNumber('user.age')
const onBirthday = useCallback(() => {
setAge((prev) => (prev ?? 0) + 1)
}, [setAge])
```
### Clearing a key
Pass `undefined` to the setter to remove the key:
```tsx
const [username, setUsername] = useMMKVString('user.name')
const onLogout = useCallback(() => {
setUsername(undefined) // removes 'user.name' from storage
}, [setUsername])
```
### Typed objects
```tsx
type User = {
id: string
username: string
age: number
}
function App() {
const [user, setUser] = useMMKVObject<User>('user')
if (user == null) return <Text>Loading...</Text>
return <Text>{user.username}</Text>
}
```
`useMMKVObject` handles `JSON.stringify`/`JSON.parse` internally.
### Getting an MMKV instance in a component
```tsx
function App() {
const storage = useMMKV()
const onLogin = useCallback((username: string) => {
storage.set('user.name', username)
}, [storage])
}
```
### Using a custom instance
```tsx
function App() {
const userStorage = useMMKV({ id: `${userId}.storage` })
const [username, setUsername] = useMMKVString('user.name', userStorage)
return <Text>{username}</Text>
}
```
### Listening for changes
```tsx
function App() {
useMMKVListener((key) => {
console.log(`Value for "${key}" changed!`)
})
}
```
With a specific instance:
```tsx
function App() {
const storage = useMMKV({ id: `${userId}.storage` })
useMMKVListener((key) => {
console.log(`Value for "${key}" changed in user storage!`)
}, storage)
}
```
### Tracking all keys
```tsx
function App() {
const storage = useMMKV()
const keys = useMMKVKeys(storage)
return <Text>Stored keys: {keys.join(', ')}</Text>
}
```
## Gotchas
- **Setter with `undefined` deletes the key.** This is intentional — it maps to `storage.remove(key)`.
- **Hooks re-render on every change to that key.** If you write to a key very frequently (e.g. every frame), the component will re-render on every write. Consider throttling or using `storage.set()` directly instead of the hook setter.
- **`useMMKVObject` re-parses when the stored value changes.** Parsing is memoized on the underlying JSON string, so it does not re-parse on every render — but every write to that key triggers a `JSON.parse`. For large objects written frequently, this can cause noticeable performance issue.
- **`useMMKV()` without arguments returns the default instance.** Pass `{ id: '...' }` to get a specific one.
## Pointers
- Source: [hooks/](https://github.com/mrousavy/react-native-mmkv/tree/main/packages/react-native-mmkv/src/hooks)
- Hooks: [useMMKVString.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/hooks/useMMKVString.ts), [useMMKVNumber.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/hooks/useMMKVNumber.ts), [useMMKVBoolean.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/hooks/useMMKVBoolean.ts), [useMMKVBuffer.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/hooks/useMMKVBuffer.ts), [useMMKVObject.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/hooks/useMMKVObject.ts), [useMMKV.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/hooks/useMMKV.ts), [useMMKVListener.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/hooks/useMMKVListener.ts), [useMMKVKeys.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/hooks/useMMKVKeys.ts)
- Tests: [hooks.test.tsx](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/__tests__/hooks.test.tsx)
- Related: [listeners.md](./listeners.md), [crud-operations.md](./crud-operations.md)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |