Skip to content
Blog

Local Storage with shared_preferences in Flutter: The 2026 API Landscape

Choose between SharedPreferencesAsync and SharedPreferencesWithCache in shared_preferences 2.5.6, read and write typed values, migrate off the legacy API, and know when to reach for something else.

Published on • November 2, 2026

AI Assistant

Flags, themes, and first-run state belong in lightweight key-value storage, and shared_preferences (2.5.6, a Flutter Favorite on pub.dev) covers all six Flutter platforms (docs.flutter.dev). Since 2.3.0 it ships three APIs, and the original SharedPreferences is slated for deprecation.

Choosing the Right API

  • SharedPreferences (legacy) — synchronous getters behind a cache, keys auto-prefixed with flutter., scheduled for deprecation; migrate it away.
  • SharedPreferencesWithCache — one async create(), then synchronous reads; best when hot-path code reads the same few keys constantly.
  • SharedPreferencesAsync — no cache at all, every call reaches the platform: always async, always fresh; the default choice for new code.

All three store only int, double, bool, String, and List<String>.

SharedPreferencesAsync: Always Fresh

Every operation returns a Future, so a stale read is impossible — even across isolates or background engine instances:

final prefs = SharedPreferencesAsync();

await prefs.setBool('repeat', true);
await prefs.setString('theme', 'dark');
await prefs.setStringList('tags', ['flutter', 'state']);

final theme = await prefs.getString('theme'); // null if unset
await prefs.remove('repeat');
await prefs.clear(allowList: {'theme', 'tags'}); // scoped clear

On Android this uses DataStore Preferences by default, the platform-recommended store. To read keys that native code wrote into legacy Android SharedPreferences, pass SharedPreferencesAsyncAndroidOptions with SharedPreferencesAndroidBackendLibrary.SharedPreferences.

SharedPreferencesWithCache: Sync Reads

After the async setup, getters are synchronous — handy inside build():

final prefs = await SharedPreferencesWithCache.create(
  cacheOptions: const SharedPreferencesWithCacheOptions(
    allowList: {'theme', 'tags'},
  ),
);

await prefs.setString('theme', 'dark');
final theme = prefs.getString('theme'); // no await

The cache goes stale when another isolate, another engine instance (say firebase_messaging’s background context), or raw native code writes the same store — call prefs.reload() before trusting a read. If most reads need a reload, use SharedPreferencesAsync instead.

Where the Bytes Land

Android → DataStore/SharedPreferences, iOS/macOS → NSUserDefaults, Linux → $XDG_DATA_HOME, Windows → roaming AppData, Web → LocalStorage. Support starts at Android SDK 24 and iOS 13; Windows, macOS, Linux, and web are all covered.

Migrating Off the Legacy API

The helper copies legacy values into the async store; it is safe to run on every launch as long as migrationCompletedKey is never changed or deleted:

import 'package:shared_preferences/util/legacy_to_async_migration_util.dart';

await migrateLegacySharedPreferencesToSharedPreferencesAsyncIfNecessary(
  legacySharedPreferencesInstance: await SharedPreferences.getInstance(),
  sharedPreferencesAsyncOptions: const SharedPreferencesOptions(),
  migrationCompletedKey: 'migrationCompleted',
);

When Not to Use It

Writes are asynchronous and nothing guarantees they hit disk before the call returns, so never store secrets or critical data here — reach for flutter_secure_storage with tokens and keys, and Hive, Drift, or sqflite for structured, queryable records.

Pick the API by how fresh your reads must be: SharedPreferencesAsync by default, SharedPreferencesWithCache for hot synchronous reads — and never for anything that must not be lost.