react-native-mmkv
MMKV is an efficient, mobile, key-value storage framework developed by WeChat. With the @amazon-devices/react-native-mmkv library, you can use MMKV inside your React Native app through fast and direct JS bindings to the native C++ library. See Tencent/MMKV for more information.
Installation
- Add the dependency in the
package.jsonfile:"dependencies": { ... "@amazon-devices/react-native-mmkv": "~1.0.0", ... } - Reinstall dependencies using the
npm installcommand.
Example
Example of creating simple storage for random key-value pairs.
import React, { useState } from 'react';
import { Button, StyleSheet, Text, View } from 'react-native';
import { MMKV, useMMKVString, useMMKVNumber, useMMKVBoolean } from '@amazon-devices/react-native-mmkv';
const storage = new MMKV();
export const App = () => {
const [hookUsername, setHookUsername] = useMMKVString('hookUsername');
const [hookAge, setHookAge] = useMMKVNumber('hookAge');
const [hookIsLoggedIn, setHookIsLoggedIn] = useMMKVBoolean('hookIsLoggedIn');
const [status, setStatus] = useState<string>("");
const handleSetData = () => {
storage.set('username', 'JohnDoe');
storage.set('isLoggedIn', true);
storage.set('age', 30);
setStatus('Stored username, isLoggedIn and age');
};
const handleGetStringData = () => {
const username = storage.getString('username');
setStatus(`Retrieved Data Username: ${username || 'None'}`);
};
const handleGetNumberData = () => {
const age = storage.getNumber('age');
setStatus(`Retrieved Data Age: ${age}`);
};
const handleGetBooleanData = () => {
const isLoggedIn = storage.getBoolean('isLoggedIn');
setStatus(`Retrieved Data Is Logged In: ${isLoggedIn}`);
};
const handleCheckKey = () => {
const hasUsernameKey = storage.contains('username');
setStatus(`Username key exists: ${hasUsernameKey}`);
};
const handleListKeys = () => {
const allKeys = storage.getAllKeys();
setStatus(`Keys: ${allKeys.join(', ')}`);
};
const handleDeleteKey = () => {
storage.delete('username');
setStatus('Deleted the "username" key.');
};
const handleClearAll = () => {
storage.clearAll();
setStatus('All data have been cleared from storage.');
};
const handleRecryptStorage = () => {
storage.recrypt('newEncryptionKey');
setStatus('Stored values have been recrypted with a new key.');
};
const handleDisplaySize = () => {
setStatus(`Stored size: ${storage.size} bytes`);
};
const handleHookSetData = () => {
setHookUsername('JaneDoe');
setHookIsLoggedIn(false);
setHookAge(25);
setStatus('Stored username, isLoggedIn and age');
};
const handleUseMMKVStringData = () => {
setStatus(`Retrieved Hook Username: ${hookUsername || 'None'}`);
};
const handleUseMMKVNumberData = () => {
setStatus(`Retrieved Hook Age: ${hookAge}`);
};
const handleUseMMKVBooleanData = () => {
setStatus(`Retrieved Hook Hook Is Logged In: ${hookIsLoggedIn}`);
};
return (
<View style={styles.container} testID="mmkv-app-container">
<Text style={styles.title}>React Native MMKV Example</Text>
<Text style={styles.title} testID="mmkv-status">Status: {status}</Text>
<Button title="Set Data" onPress={handleSetData} testID="mmkv-app-set-button" />
<Button title="Get String" onPress={handleGetStringData} testID="mmkv-app-get-string-button" />
<Button title="Get Number" onPress={handleGetNumberData} testID="mmkv-app-get-number-button" />
<Button title="Get Boolean" onPress={handleGetBooleanData} testID="mmkv-app-get-boolean-button"/>
<Button title="Check If Key Exists" onPress={handleCheckKey} testID="mmkv-app-contains-button"/>
<Button title="List All Keys" onPress={handleListKeys} testID="mmkv-app-get-all-keys-button"/>
<Button title="Delete 'Username' Key" onPress={handleDeleteKey} testID="mmkv-app-delete-key-button"/>
<Button title="Clear All Data" onPress={handleClearAll} testID="mmkv-app-clear-all-button"/>
<Button title="Recrypt Storage" onPress={handleRecryptStorage} testID="mmkv-app-recrypt-button"/>
<Button title="Display Storage Size" onPress={handleDisplaySize} testID="mmkv-app-size-button"/>
<Button title="Hook Set Data" onPress={handleHookSetData} testID="mmkv-app-hook-set-button"/>
<Button title="Hook Get String Data" onPress={handleUseMMKVStringData} testID="mmkv-app-hook-get-string-button"/>
<Button title="Hook Get Number Data" onPress={handleUseMMKVNumberData} testID="mmkv-app-hook-get-number-button"/>
<Button title="Hook Get Boolean Data" onPress={handleUseMMKVBooleanData} testID="mmkv-app-hook-get-boolean-button"/>
</View>
);
};
const styles = StyleSheet.create({
container: {
flexGrow: 1,
justifyContent: 'center',
alignItems: 'center',
padding: 20,
backgroundColor: '#fff',
},
title: {
fontSize: 20,
marginBottom: 20,
textAlign: 'center',
},
button: {
marginVertical: 10,
},
});
API reference
MMKV library on Vega provides TurboModules, which add support for the following native MMKV methods.
See the dedicated documentation page for more information about this library and API reference.
Native MMKV
| Method | Description |
|---|---|
MMKV |
A base storage class for MMKV. |
size |
Gets the current total size of the storage, in bytes. |
set |
Sets a value for the given key. |
getBoolean |
Gets the boolean value for the given key or undefined if it doesn't exist. |
getString |
Gets the string value for the given key or undefined if it doesn't exist. |
getNumber |
Gets the number value for the given key or undefined if it doesn't exist. |
getBuffer |
Gets a raw buffer of unsigned 8-bit (0-255) data. |
contains |
Checks whether the given key is stored in this MMKV instance. |
delete |
Deletes the given key. |
getAllKeys |
Gets all keys. |
clearAll |
Deletes all keys. |
recrypt |
Sets (or updates) the encryption-key to encrypt all data in this MMKV instance with. |
trim |
Trims the storage space and clears the memory cache. |
toString |
Gets the string representation of MMKV. |
toJSON |
Gets the JSON representation of MMKV. |
addOnValueChangedListener |
Adds a value changed listener. The app calls the listener whenever any value in the storage instance changes (is set or deleted). |
Hooks
| Method | Description |
|---|---|
useMMKV |
Use the default, shared MMKV instance. |
useMMKVString |
Use the string value of the given key from the given MMKV storage instance. |
useMMKVNumber |
Use the number value of the given key from the given MMKV storage instance. |
useMMKVBoolean |
Use the boolean value of the given key from the given MMKV storage instance. |
useMMKVObject |
Use an object value of the given key from the given MMKV storage instance. |
useMMKVListener |
Listen for changes in the given MMKV storage instance. |
Configuration
| Method | Description |
|---|---|
id |
The MMKV instance's ID. If you want to use multiple instances, make sure to use different IDs. |
path |
The MMKV instance's root path. |
encryptionKey |
The MMKV instance's encryption/decryption key. |
mode |
Configures the processing mode for MMKV. |
Mode
| Method | Description |
|---|---|
SINGLE_PROCESS |
The app only uses the MMKV instance as a single process. |
MULTI_PROCESS |
The app uses the MMKV instance potentially as multiple processes, such as app clips, share extensions, or background services. |
Known Issues
- The
recryptmethod isn't supported on a Vega Virtual Device. - The
useMMKVBufferhook isn't supported.
Supported react-native-kepler versions
| package version | @amazon-devices/react-native-kepler version |
|---|---|
| 1.0.x+3.0.2 | 2.0.x+rn0.72.0 |
Additional resources
For information on other libraries, see Supported Third-Party Libraries and Services.
Last updated: Sep 30, 2025

