as

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

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

  1. Add the dependency in package.json file:

    Copied to clipboard.

     "dependencies": {
          ...
          "@amazon-devices/react-native-mmkv": "~1.0.0",
          ...
     }
    
  2. Reinstall dependencies using 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 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 Device
  • useMMKVBuffer 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