as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Get Started
Design and Develop
Publish
Reference
Support

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

  1. Add the dependency in the package.json file:

    Copied to clipboard.

     "dependencies": {
          ...
          "@amazon-devices/react-native-mmkv": "~1.0.0",
          ...
     }
    
  2. Reinstall dependencies using the npm install command.

Example

Example of creating simple storage for random key-value pairs.

Copied to clipboard.

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 recrypt method isn't supported on a Vega Virtual Device.
  • The useMMKVBuffer hook 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