@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
package.jsonfile:"dependencies": { ... "@amazon-devices/react-native-mmkv": "~1.0.0", ... } -
Reinstall dependencies using the
npm installcommand.
Examples
An example that creates 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 documentation 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 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 | Configure 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 and limitations
- The
recryptmethod isn’t supported on a Vega Virtual Device. - The
useMMKVBufferhook isn’t supported.
Supported versions
| package version | @amazon-devices/react-native-kepler version |
|---|---|
| 1.0.x+3.0.2 | 2.0.x+rn0.72.0 |

