API

getItem

Gets a string value for given key. This function can either return a string value for existing key or return null otherwise.

In order to store object value, you need to deserialize it, e.g. using JSON.parse().

Note (legacy): you can use optional callback as an alternative for returned promise.

Signature:

static getItem(key: string, [callback]: ?(error: ?Error, result: ?string) => void): Promise

Returns:

Promise resolving with a string value, if entry exists for given key, or null otherwise.

Promise can also be rejected in case of underlying storage error.

Example:

getMyStringValue = async () => {
try {
return await AsyncStorage.getItem('@key')
} catch(e) {
// read error
}
console.log('Done.')
}
getMyObject = async () => {
try {
const jsonValue = await AsyncStorage.getItem('@key')
return jsonValue != null ? JSON.parse(jsonValue) : null
} catch(e) {
// read error
}
console.log('Done.')
}


setItem

Sets a string value for given key. This operation can either modify an existing entry, if it did exist for given key, or add new one otherwise.

In order to store object value, you need to serialize it, e.g. using JSON.stringify().

Note (legacy): you can use optional callback as an alternative for returned promise.

Signature:

static setItem(key: string, value: string, [callback]: ?(error: ?Error) => void): Promise

Returns:

Promise resolving when the set operation is completed.

Promise can also be rejected in case of underlying storage error.

Example:

setStringValue = async (value) => {
try {
await AsyncStorage.setItem('key', value)
} catch(e) {
// save error
}
console.log('Done.')
}
setObjectValue = async (value) => {
try {
const jsonValue = JSON.stringify(value)
await AsyncStorage.setItem('key', jsonValue)
} catch(e) {
// save error
}
console.log('Done.')
}


mergeItem

Merges an existing value stored under key, with new value, assuming both values are stringified JSON. NOTE: This is not supported by all native implementations.

Signature:

static mergeItem(key: string, value: string, [callback]: ?(error: ?Error) => void): Promise

Returns:

Promise with merged data, if exists, null otherwise.

Example:

const USER_1 = {
name: 'Tom',
age: 20,
traits: {
hair: 'black',
eyes: 'blue'
}
}
const USER_2 = {
name: 'Sarah',
age: 21,
hobby: 'cars',
traits: {
eyes: 'green',
}
}
mergeUsers = async () => {
try {
//save first user
await AsyncStorage.setItem('@MyApp_user', JSON.stringify(USER_1))
// merge USER_2 into saved USER_1
await AsyncStorage.mergeItem('@MyApp_user', JSON.stringify(USER_2))
// read merged item
const currentUser = await AsyncStorage.getItem('@MyApp_user')
console.log(currentUser)
// console.log result:
// {
// name: 'Sarah',
// age: 21,
// hobby: 'cars',
// traits: {
// eyes: 'green',
// hair: 'black'
// }
// }
}
}


removeItem

Removes item for a key, invokes (optional) callback once completed.

Signature:

static removeItem(key: string, [callback]: ?(error: ?Error) => void): Promise

Returns:

Promise object.

Example:

removeValue = async () => {
try {
await AsyncStorage.removeItem('@MyApp_key')
} catch(e) {
// remove error
}
console.log('Done.')
}


getAllKeys

Returns all keys known to your App, for all callers, libraries, etc. Once completed, invokes callback with errors (if any) and array of keys.

Signature:

static getAllKeys([callback]: ?(error: ?Error, keys: ?Array<string>) => void): Promise

Returns:

Promise object.

Example:

getAllKeys = async () => {
let keys = []
try {
keys = await AsyncStorage.getAllKeys()
} catch(e) {
// read key error
}
console.log(keys)
// example console.log result:
// ['@MyApp_user', '@MyApp_key']
}


multiGet

Fetches multiple key-value pairs for given array of keys in a batch. Once completed, invokes callback with errors (if any) and results.

Signature:

static multiGet(keys: Array<string>, [callback]: ?(errors: ?Array<Error>, result: ?Array<Array<string>>) => void): Promise

Returns:

Promise of array with coresponding key-value pairs found, stored as [key, value] array.

Example:

getMultiple = async () => {
let values
try {
values = await AsyncStorage.multiGet(['@MyApp_user', '@MyApp_key'])
} catch(e) {
// read error
}
console.log(values)
// example console.log output:
// [ ['@MyApp_user', 'myUserValue'], ['@MyApp_key', 'myKeyValue'] ]
}


multiSet

Stores multiple key-value pairs in a batch. Once completed, callback with any errors will be called.

Signature:

static multiSet(keyValuePairs: Array<Array<string>>, [callback]: ?(errors: ?Array<Error>) => void): Promise

Returns:

Promise object.

Example:

multiSet = async () => {
const firstPair = ["@MyApp_user", "value_1"]
const secondPair = ["@MyApp_key", "value_2"]
try {
await AsyncStorage.multiSet([firstPair, secondPair])
} catch(e) {
//save error
}
console.log("Done.")
}


multiMerge

Multiple merging of existing and new values in a batch. Assumes that values are stringified JSON. Once completed, invokes callback with errors (if any). NOTE: This is not supported by all native implementations.

Signature:

static multiMerge(keyValuePairs: Array<Array<string>>, [callback]: ?(errors: ?Array<Error>) => void): Promise

Returns:

Promise object.

Example:

const USER_1 = {
name: 'Tom',
age: 30,
traits: {hair: 'brown'},
};
const USER_1_DELTA = {
age: 31,
traits: {eyes: 'blue'},
};
const USER_2 = {
name: 'Sarah',
age: 25,
traits: {hair: 'black'},
};
const USER_2_DELTA = {
age: 26,
traits: {hair: 'green'},
};
const multiSet = [
["@MyApp_USER_1", JSON.stringify(USER_1)],
["@MyApp_USER_2", JSON.stringify(USER_2)]
]
const multiMerge = [
["@MyApp_USER_1", JSON.stringify(USER_1_DELTA)],
["@MyApp_USER_2", JSON.stringify(USER_2_DELTA)]
]
mergeMultiple = async () => {
let currentlyMerged
try {
await AsyncStorage.multiSet(multiSet)
await AsyncStorage.multiMerge(multiMerge)
currentlyMerged = await AsyncStorage.multiGet(['@MyApp_USER_1', '@MyApp_USER_2'])
} catch(e) {
// error
}
console.log(currentlyMerged)
// console.log output:
// [
// [
// 'USER_1',
// {
// name:"Tom",
// age:30,
// traits: {
// hair: 'brown'
// eyes: 'blue'
// }
// }
// ],
// [
// 'USER_2',
// {
// name:'Sarah',
// age:26,
// traits: {
// hair: 'green'
// }
// }
// ]
// ]
}


multiRemove

Clears multiple key-value entries for given array of keys in a batch. Once completed, invokes a callback with errors (if any).

Signature:

static multiRemove(keys: Array<string>, [callback]: ?(errors: ?Array<Error>) => void)

Returns:

Promise object.

Example:

removeFew = async () => {
const keys = ['@MyApp_USER_1', '@MyApp_USER_2']
try {
await AsyncStorage.multiRemove(keys)
} catch(e) {
// remove error
}
console.log('Done')
}


clear

Removes whole AsyncStorage data, for all clients, libraries, etc. You probably want to use removeItem or multiRemove to clear only your App's keys.

Signature:

static clear([callback]: ?(error: ?Error) => void): Promise

Returns:

Promise object.

Example:

clearAll = async () => {
try {
await AsyncStorage.clear()
} catch(e) {
// clear error
}
console.log('Done.')
}

useAsyncStorage

Note: A hooks-like interface that we're experimenting with. This will change in the nearest future to fully leverage Hooks API, so feel free to follow this discussion to learn more.

The useAsyncStorage returns an object that exposes all methods that allow you to interact with the stored value.

Signature:

static useAsyncStorage(key: string): {
getItem: (
callback?: ?(error: ?Error, result: string | null) => void,
) => Promise<string | null>,
setItem: (
value: string,
callback?: ?(error: ?Error) => void,
) => Promise<null>,
mergeItem: (
value: string,
callback?: ?(error: ?Error) => void,
) => Promise<null>,
removeItem: (callback?: ?(error: ?Error) => void) => Promise<null>,
}

Returns:

object

Specific Example:

You can replace your App.js with the following to see it in action.

import React, { useState, useEffect } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { useAsyncStorage } from '@react-native-async-storage/async-storage';
export default function App() {
const [value, setValue] = useState('value');
const { getItem, setItem } = useAsyncStorage('@storage_key');
const readItemFromStorage = async () => {
const item = await getItem();
setValue(item);
};
const writeItemToStorage = async newValue => {
await setItem(newValue);
setValue(newValue);
};
useEffect(() => {
readItemFromStorage();
}, []);
return (
<View style={{ margin: 40 }}>
<Text>Current value: {value}</Text>
<TouchableOpacity
onPress={() =>
writeItemToStorage(
Math.random()
.toString(36)
.substr(2, 5)
)
}
>
<Text>Update value</Text>
</TouchableOpacity>
</View>
);
}

In this example:

  1. On mount, we read the value at @storage_key and save it to the state under value
  2. When pressing on "update value", a new string gets generated, saved to async storage, and to the component state
  3. Try to reload your app - you'll see that the last value is still being read from async storage