README.md

May 8, 2026 · View on GitHub

V4 Docs	old V3 Docs

MMKV

The fastest key/value storage for React Native.

This library helped you? Consider sponsoring!

MMKV is an efficient, small mobile key-value storage framework developed by WeChat. See Tencent/MMKV for more information
react-native-mmkv is a library that allows you to easily use MMKV inside your React Native app through fast and direct JS bindings to the native C++ library.

Features

Get and set strings, booleans, numbers and ArrayBuffers
Fully synchronous calls, no async/await, no Promises, no Bridge.
Encryption support (secure storage)
Multiple instances support (separate user-data with global data)
Customizable storage location
High performance because everything is written in C++
~30x faster than AsyncStorage
Uses JSI and C++ NitroModules instead of the "old" Bridge
iOS, Android and Web support
Easy to use React Hooks API

Important

You're looking at MMKV V4. If you're still on V3, check out the V3 docs here!
react-native-mmkv V4 is now a Nitro Module. See the V4 Upgrade Guide for more information.

Benchmark

StorageBenchmark compares popular storage libraries against each other by reading a value from storage for 1000 times:

MMKV vs other storage libraries: Reading a value from Storage 1000 times.
Measured in milliseconds on an iPhone 11 Pro, lower is better.

Installation

React Native

npm install react-native-mmkv react-native-nitro-modules
cd ios && pod install

Expo

npx expo install react-native-mmkv react-native-nitro-modules
npx expo prebuild

To create a new instance of the MMKV storage, use the MMKV constructor. It is recommended that you re-use this instance throughout your entire app instead of creating a new instance each time, so export the storage object.

Default

import { createMMKV } from 'react-native-mmkv'

export const storage = createMMKV()

This creates a new storage instance using the default MMKV storage ID (mmkv.default).

App Groups or Extensions

If you want to share MMKV data between your app and other apps or app extensions in the same group, open Info.plist and create an AppGroupIdentifier key with your app group's value. MMKV will then automatically store data inside the app group which can be read and written to from other apps or app extensions in the same group by making use of MMKV's multi processing mode. See Configuring App Groups.

Customize

import { createMMKV } from 'react-native-mmkv'

export const storage = createMMKV({
  id: `user-${userId}-storage`,
  path: `${USER_DIRECTORY}/storage`,
  encryptionKey: 'hunter2',
  encryptionType: 'AES-256',
  mode: 'multi-process',
  readOnly: false,
  compareBeforeSet: false,
})

This creates a new storage instance using a custom MMKV storage ID. By using a custom storage ID, your storage is separated from the default MMKV storage of your app.

The following values can be configured:

id: The MMKV instance's ID. If you want to use multiple instances, use different IDs. For example, you can separate the global app's storage and a logged-in user's storage. (required if path or encryptionKey fields are specified, otherwise defaults to: 'mmkv.default')
path: The MMKV instance's root path. By default, MMKV stores file inside $(Documents)/mmkv/. You can customize MMKV's root directory on MMKV initialization (documentation: iOS / Android)
encryptionKey: The MMKV instance's encryption/decryption key. By default, MMKV stores all key-values in plain text on file, relying on iOS's/Android's sandbox to make sure the file is encrypted. Should you worry about information leaking, you can choose to encrypt MMKV. (documentation: iOS / Android)
encryptionType: The MMKV instance's encryption/decryption algorithm. By default, AES-128 encryption will be used, but you can switch to AES-256 for advanced security.
mode: The MMKV's process behaviour - when set to multi-process, the MMKV instance will assume data can be changed from the outside (e.g. App Clips, Extensions or App Groups).
readOnly: Whether this MMKV instance should be in read-only mode. This is typically more efficient and avoids unwanted writes to the data if not needed. Any call to set(..) will throw.
compareBeforeSet: Whether this MMKV instance will compare values for equality before writing them to disk. By default this is disabled, enabling it might improve performance if values are repeatedly written to disk, even if they are already persisted.

Set

storage.set('user.name', 'Marc')
storage.set('user.age', 21)
storage.set('is-mmkv-fast-asf', true)

Get

const username = storage.getString('user.name') // 'Marc'
const age = storage.getNumber('user.age') // 21
const isMmkvFastAsf = storage.getBoolean('is-mmkv-fast-asf') // true

Hooks

const [username, setUsername] = useMMKVString('user.name')
const [age, setAge] = useMMKVNumber('user.age')
const [isMmkvFastAsf, setIsMmkvFastAsf] = useMMKVBoolean('is-mmkv-fast-asf')

Keys

// checking if a specific key exists
const hasUsername = storage.contains('user.name')

// getting all keys
const keys = storage.getAllKeys() // ['user.name', 'user.age', 'is-mmkv-fast-asf']

// delete a specific key + value
const wasRemoved = storage.remove('user.name')

// delete all keys
storage.clearAll()

Objects

const user = {
  username: 'Marc',
  age: 21
}

// Serialize the object into a JSON string
storage.set('user', JSON.stringify(user))

// Deserialize the JSON string into an object
const jsonUser = storage.getString('user') // { 'username': 'Marc', 'age': 21 }
const userObject = JSON.parse(jsonUser)

Encryption

// encrypt all data with a private key using AES-128
storage.encrypt('hunter2')
// encrypt all data with a private key using AES-256
storage.encrypt('hunter2again', 'AES-256')

// remove encryption
storage.decrypt()

Buffers

const buffer = new ArrayBuffer(3)
const dataWriter = new Uint8Array(buffer)
dataWriter[0] = 1
dataWriter[1] = 100
dataWriter[2] = 255
storage.set('someToken', buffer)

const buffer = storage.getBuffer('someToken')
console.log(buffer) // [1, 100, 255]

Size

// get size of MMKV storage in bytes
const size = storage.size
if (size >= 4096) {
  // clean unused keys and clear memory cache
  storage.trim()
}

Importing all data from another MMKV instance

To import all keys and values from another MMKV instance, use importAllFrom(...):

const storage = createMMKV(...)
const otherStorage = createMMKV(...)

const importedCount = storage.importAllFrom(otherStorage)

Check if an MMKV instance exists

To check if an MMKV instance exists, use existsMMKV(...):

import { existsMMKV } from 'react-native-mmkv'

const exists = existsMMKV('my-instance')

Delete an MMKV instance

To delete an MMKV instance, use deleteMMKV(...):

import { deleteMMKV } from 'react-native-mmkv'

const wasDeleted = deleteMMKV('my-instance')

Log Level

By default, MMKV logs at Debug level in debug builds and Warning level in release builds. You can override this at build time to control the verbosity of MMKV's native logs.

Value	Level
0	Debug
1	Info
2	Warning
3	Error
4	None

Android

Set MMKV_logLevel in your app's android/gradle.properties:

MMKV_logLevel=4

iOS

Set $MMKVLogLevel in your app's ios/Podfile, then run pod install:

$MMKVLogLevel = 4

Or use an environment variable during pod install:

MMKV_LOG_LEVEL=4 pod install

Testing with Jest or Vitest

A mocked MMKV instance is automatically used when testing with Jest or Vitest, so you will be able to use createMMKV() as per normal in your tests. Refer to example/__tests__/MMKV.harness.ts for an example using Jest.

Documentation

LocalStorage and In-Memory Storage (Web)

If a user chooses to disable LocalStorage in their browser, the library will automatically provide a limited in-memory storage as an alternative. However, this in-memory storage won't persist data, and users may experience data loss if they refresh the page or close their browser. To optimize user experience, consider implementing a suitable solution within your app to address this scenario.

Limitations

react-native-mmkv V4 requires react-native 0.76 or higher.
Since react-native-mmkv uses JSI for synchronous native method invocations, remote debugging (e.g. with Chrome) is no longer possible. Instead, you should use Flipper or React DevTools.