Skip to content

callstackincubator/apex-software-factory / .agents/skills/react-native-mmkv

react-native-mmkv

Verified

Fast 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.

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)
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall