Reading and Writing with AsyncStorage
Install @react-native-async-storage/async-storage, use setItem and getItem to store and retrieve string values, and handle the returned Promises correctly.
Reading and Writing with AsyncStorage is a free React Native Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the React Native Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What Is AsyncStorage?
AsyncStorage is React Native's persistent key-value storage system. It stores data as strings on the device's local file system, making it available even after the app is closed and reopened. It works on both iOS and Android and supports any string-serializable value. All operations are asynchronous and return Promises, so you must await them or chain .then().
Installing the Package
The community AsyncStorage package must be installed separately in modern React Native and Expo projects. It is no longer bundled with React Native core. Use npx expo install (instead of plain npm) so Expo picks the compatible version for your SDK.
npx expo install @react-native-async-storage/async-storageWriting Data with setItem
AsyncStorage.setItem(key, value) stores a string value at the given key. Both the key and the value must be strings. If the key already exists, the value is overwritten. Always await the call inside a try-catch block to handle potential errors, such as storage being full on the device.
import AsyncStorage from '@react-native-async-storage/async-storage';
async function saveUsername(username: string) {
try {
await AsyncStorage.setItem('username', username);
console.log('Saved successfully');
} catch (error) {
console.error('Failed to save username:', error);
}
}Reading Data with getItem
AsyncStorage.getItem(key) retrieves the string value for the given key. It returns null if the key does not exist — handle this case to avoid runtime errors. A common pattern is to check for null and fall back to a default value when the app launches for the first time.
async function loadUsername(): Promise<string> {
try {
const value = await AsyncStorage.getItem('username');
if (value !== null) {
return value;
}
return 'Guest'; // default when key does not exist
} catch (error) {
console.error('Failed to load username:', error);
return 'Guest';
}
}Removing Data with removeItem
AsyncStorage.removeItem(key) deletes the entry for the given key from storage. After removal, calling getItem for that key returns null. Use this when the user logs out, resets preferences, or deletes their account — any time you need to erase specific stored data without clearing everything.
async function clearSession() {
try {
await AsyncStorage.removeItem('authToken');
await AsyncStorage.removeItem('userId');
console.log('Session cleared');
} catch (error) {
console.error('Failed to clear session:', error);
}
}Loading Data on App Start with useEffect
A typical pattern is to load persisted data into component state when a screen mounts. Use useEffect with an empty dependency array so it runs only once on mount. Set a loading flag while the data loads and clear it when the read completes so the UI shows a spinner instead of blank or stale content.
export default function SettingsScreen() {
const [theme, setTheme] = React.useState('light');
const [loading, setLoading] = React.useState(true);
useEffect(() => {
async function loadTheme() {
const saved = await AsyncStorage.getItem('theme');
if (saved) setTheme(saved);
setLoading(false);
}
loadTheme();
}, []);
if (loading) return <ActivityIndicator />;
return <Text>Current theme: {theme}</Text>;
}Batch Operations with multiSet and multiGet
Reading or writing several keys in a loop is inefficient. Use AsyncStorage.multiSet and AsyncStorage.multiGet to perform batch operations in a single native call. multiSet accepts an array of [key, value] pairs, and multiGet returns an array of the same format with the retrieved values.
// Write multiple keys in one call
await AsyncStorage.multiSet([
['theme', 'dark'],
['language', 'en'],
['fontSize', '16'],
]);
// Read multiple keys in one call
const pairs = await AsyncStorage.multiGet(['theme', 'language', 'fontSize']);
const settings = Object.fromEntries(pairs);
console.log(settings); // { theme: 'dark', language: 'en', fontSize: '16' }Listing All Keys
AsyncStorage.getAllKeys() returns an array of every key currently stored by the app. This is useful for debugging, for building a cache-clearing screen, or for reading all entries without knowing the keys in advance. Combine it with multiGet to load the full storage contents at once.
async function debugStorage() {
const keys = await AsyncStorage.getAllKeys();
console.log('All keys:', keys);
const pairs = await AsyncStorage.multiGet(keys);
pairs.forEach(([key, value]) => {
console.log(key, '->', value);
});
}Clearing All Data with clear
AsyncStorage.clear() deletes all keys stored by the app. Use this with caution — it is a destructive operation with no built-in undo. It is appropriate for a factory reset feature or for wiping all data during development, but never call it without explicit user confirmation in a production app.
async function factoryReset() {
Alert.alert('Reset App', 'This will delete all your data. Are you sure?', [
{ text: 'Cancel', style: 'cancel' },
{
text: 'Reset',
style: 'destructive',
onPress: async () => {
await AsyncStorage.clear();
navigation.reset({ index: 0, routes: [{ name: 'Onboarding' }] });
},
},
]);
}Error Handling Best Practices
AsyncStorage operations can fail when the device is low on storage or when a native bridge error occurs. Always wrap reads and writes in try-catch blocks. For reads, return a sensible default on error. For writes, consider queuing the write to retry later or notifying the user that their setting could not be saved.
async function safeSave(key: string, value: string) {
try {
await AsyncStorage.setItem(key, value);
return true;
} catch (err) {
if (__DEV__) console.error('AsyncStorage write failed:', err);
// Optionally: show a Snackbar or Toast to the user
return false;
}
}AsyncStorage Limits and Alternatives
AsyncStorage is designed for small amounts of data — user preferences, tokens, and simple settings. It is not suitable for large datasets (images, documents, or thousands of records), for which you should consider SQLite (via expo-sqlite). Also note that AsyncStorage data is not encrypted by default, so use Expo SecureStore for sensitive credentials.
Quick Check
Test your understanding of React Native Mobile Development concepts from this lesson.
Lesson Recap
In this lesson you learned: setItem and getItem are the core AsyncStorage APIs for writing and reading string values keyed by name, multiSet and multiGet batch multiple operations into a single efficient native call, and null checking is essential because getItem returns null for keys that have never been written. Next up we explore storing and parsing JSON objects in AsyncStorage.
Frequently asked questions
Is the “Reading and Writing with AsyncStorage” lesson free?
Yes — the full text of “Reading and Writing with AsyncStorage” is free to read here on the web, and the React Native Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the React Native Academy course, upgrade to CoddyKit PRO.
What will I learn in “Reading and Writing with AsyncStorage”?
Install @react-native-async-storage/async-storage, use setItem and getItem to store and retrieve string values, and handle the returned Promises correctly. You practise React Native Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start React Native Academy?
No prior experience is required. React Native Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Reading and Writing with AsyncStorage” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this React Native Academy lesson?
Yes. Every React Native Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Reading and Writing with AsyncStorage
- Storing and Parsing JSON Objects
- Building a Persistent Settings Screen
- Clearing Storage and Migration Strategies