react-native-mmkv
MMKV is an efficient, small mobile key-value storage framework developed by WeChat. @amazon-devices/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. See Tencent/MMKV for more information.
Installation
- Add the dependency in
package.json
file:"dependencies": { ... "@amazon-devices/react-native-mmkv": "~1.0.0", ... }
- Reinstall dependencies using
npm install
command.
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 a support for methods listed below.
See the dedicated documentation page for more info about this library, API reference and more.
Native MMKV
Method | Description |
---|---|
MMKV |
A base storage class for MMKV |
size |
Get the current total size of the storage, in bytes. |
set |
Set a value for the given key |
getBoolean |
Get the boolean value for the given key , or undefined if it does not exist. |
getString |
Get the string value for the given key , or undefined if it does not exist. |
getNumber |
Get the number value for the given key , or undefined if it does not exist. |
getBuffer |
Get a raw buffer of unsigned 8-bit (0-255) data. |
contains |
Checks whether the given key is being stored in this MMKV instance. |
delete |
Delete the given key . |
getAllKeys |
Get all keys. |
clearAll |
Delete 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 memory cache. |
toString |
Get string representation of MMKV |
toJSON |
Get JSON representation of MMKV |
addOnValueChangedListener |
Adds a value changed listener. The Listener will be called whenever any value in this storage instance changes (set or delete). |
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 |
Configure the processing mode for MMKV. |
Mode
Method | Description |
---|---|
SINGLE_PROCESS |
The MMKV instance is only used from a single process (this app). |
MULTI_PROCESS |
The MMKV instance may be used from multiple processes, such as app clips, share extensions or background services. |
Known Issues
recrypt
method is not supported on the Vega Virtual DeviceuseMMKVBuffer
hook is not 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 additonal libraries, see Supported Third-Party Libraries and Services.
Last updated: Sep 30, 2025