Shared preferences plugin

Wraps platform-specific persistent storage for simple data (NSUserDefaults on iOS and macOS, SharedPreferences on Android, etc.). Data may be persisted to disk asynchronously, and there is no guarantee that writes will be persisted to disk after returning, so this plugin must not be used for storing critical data.

Supported data types are int, double, bool, String and List<String>.

	Android	iOS	Linux	macOS	Web	Windows
Support	SDK 24+	13.0+	Any	10.15+	Any	Any

Usage

SharedPreferences vs SharedPreferencesAsync vs SharedPreferencesWithCache

Starting with version 2.3.0 there are three available APIs that can be used in this package. [SharedPreferences] is a legacy API that will be deprecated in the future. We highly encourage any new users of the plugin to use the newer [SharedPreferencesAsync] or [SharedPreferencesWithCache] APIs instead.

Consider migrating existing code to one of the new APIs. See below for more information.

Cache and async or sync getters

[SharedPreferences] and [SharedPreferencesWithCache] both use a local cache to store preferences. This allows for synchronous get calls after the initial setup call fetches the preferences from the platform. However, The cache can present issues as well:

• If you are using shared_preferences from multiple isolates, since each isolate has its own singleton and cache.
• If you are using shared_preferences in multiple engine instances (including those created by plugins that create background contexts on mobile devices, such as firebase_messaging).
• If you are modifying the underlying system preference store through something other than the shared_preferences plugin, such as native code.

This can be remedied by calling the reload method before using a getter as needed. If most get calls need a reload, consider using [SharedPreferencesAsync] instead.

[SharedPreferencesAsync] does not utilize a local cache which causes all calls to be asynchronous calls to the host platforms storage solution. This can be less performant, but should always provide the latest data stored on the native platform regardless of what process was used to store it.

Android platform storage

The [SharedPreferencesAsync] and [SharedPreferencesWithCache] APIs can use DataStore Preferences or Android SharedPreferences to store data. In most cases you should use the default option of DataStore Preferences, as it is the platform-recommended preferences storage system. However, in some cases you may need to interact with preferences that were written to SharedPreferences by code you don't control.

To use the Android SharedPreferences backend, use the SharedPreferencesAsyncAndroidOptions when using [SharedPreferencesAsync] on Android.

import 'package:shared_preferences_android/shared_preferences_android.dart';
                

const SharedPreferencesAsyncAndroidOptions options =
                    SharedPreferencesAsyncAndroidOptions(
                      backend: SharedPreferencesAndroidBackendLibrary.SharedPreferences,
                      originalSharedPreferencesOptions: AndroidSharedPreferencesStoreOptions(
                        fileName: 'the_name_of_a_file',
                      ),
                    );
                

The [SharedPreferences] API uses the native Android SharedPreferences tool to store data.

Examples

Here are small examples that show you how to use the API.

SharedPreferences

Write data

// Obtain shared preferences.
                final SharedPreferences prefs = await SharedPreferences.getInstance();
                
                // Save an integer value to 'counter' key.
                await prefs.setInt('counter', 10);
                // Save an boolean value to 'repeat' key.
                await prefs.setBool('repeat', true);
                // Save an double value to 'decimal' key.
                await prefs.setDouble('decimal', 1.5);
                // Save an String value to 'action' key.
                await prefs.setString('action', 'Start');
                // Save an list of strings to 'items' key.
                await prefs.setStringList('items', <String>['Earth', 'Moon', 'Sun']);
                

Read data

// Try reading data from the 'counter' key. If it doesn't exist, returns null.
                final int? counter = prefs.getInt('counter');
                // Try reading data from the 'repeat' key. If it doesn't exist, returns null.
                final bool? repeat = prefs.getBool('repeat');
                // Try reading data from the 'decimal' key. If it doesn't exist, returns null.
                final double? decimal = prefs.getDouble('decimal');
                // Try reading data from the 'action' key. If it doesn't exist, returns null.
                final String? action = prefs.getString('action');
                // Try reading data from the 'items' key. If it doesn't exist, returns null.
                final List<String>? items = prefs.getStringList('items');
                

Remove an entry

// Remove data for the 'counter' key.
                await prefs.remove('counter');
                

SharedPreferencesAsync

final asyncPrefs = SharedPreferencesAsync();
                
                await asyncPrefs.setBool('repeat', true);
                await asyncPrefs.setString('action', 'Start');
                
                final bool? repeat = await asyncPrefs.getBool('repeat');
                final String? action = await asyncPrefs.getString('action');
                
                await asyncPrefs.remove('repeat');
                
                // Any time a filter option is included as a method parameter, strongly consider
                // using it to avoid potentially unwanted side effects.
                await asyncPrefs.clear(allowList: <String>{'action', 'repeat'});
                

SharedPreferencesWithCache

final SharedPreferencesWithCache
                prefsWithCache = await SharedPreferencesWithCache.create(
                  cacheOptions: const SharedPreferencesWithCacheOptions(
                    // When an allowlist is included, any keys that aren't included cannot be used.
                    allowList: <String>{'repeat', 'action'},
                  ),
                );
                
                await prefsWithCache.setBool('repeat', true);
                await prefsWithCache.setString('action', 'Start');
                
                final bool? repeat = prefsWithCache.getBool('repeat');
                final String? action = prefsWithCache.getString('action');
                
                await prefsWithCache.remove('repeat');
                
                // Since the filter options are set at creation, they aren't needed during clear.
                await prefsWithCache.clear();
                

Migration and Prefixes

Migrating from SharedPreferences to SharedPreferencesAsync/WithCache

To migrate to the newer SharedPreferencesAsync or SharedPreferencesWithCache APIs, import the migration utility and provide it with the SharedPreferences instance that was being used previously, as well as the options for the desired new API options.

This can be run on every launch without data loss as long as the migrationCompletedKey is not altered or deleted.

import 'package:shared_preferences/util/legacy_to_async_migration_util.dart';
                // ···
                    const sharedPreferencesOptions = SharedPreferencesOptions();
                    final SharedPreferences prefs = await SharedPreferences.getInstance();
                    await migrateLegacySharedPreferencesToSharedPreferencesAsyncIfNecessary(
                      legacySharedPreferencesInstance: prefs,
                      sharedPreferencesAsyncOptions: sharedPreferencesOptions,
                      migrationCompletedKey: 'migrationCompleted',
                    );
                

Adding, Removing, or changing prefixes on SharedPreferences

By default, the SharedPreferences class will only read (and write) preferences that begin with the prefix flutter.. This is all handled internally by the plugin and does not require manually adding this prefix.

Alternatively, SharedPreferences can be configured to use any prefix by adding a call to setPrefix before any instances of SharedPreferences are instantiated. Calling setPrefix after an instance of SharedPreferences is created will fail. Setting the prefix to an empty string '' will allow access to all preferences created by any non-flutter versions of the app (for migrating from a native app to flutter).

If the prefix is set to a value such as '' that causes it to read values that were not originally stored by the SharedPreferences, initializing SharedPreferences may fail if any of the values are of types that are not supported by SharedPreferences. In this case, you can set an allowList that contains only preferences of supported types.

If you decide to remove the prefix entirely, you can still access previously created preferences by manually adding the previous prefix flutter. to the beginning of the preference key.

If you have been using SharedPreferences with the default prefix but wish to change to a new prefix, you will need to transform your current preferences manually to add the new prefix otherwise the old preferences will be inaccessible.

Storage location by platform

Platform	SharedPreferences	SharedPreferencesAsync/WithCache
Android	SharedPreferences	DataStore Preferences or SharedPreferences
iOS	NSUserDefaults	NSUserDefaults
Linux	In the XDG_DATA_HOME directory	In the XDG_DATA_HOME directory
macOS	NSUserDefaults	NSUserDefaults
Web	LocalStorage	LocalStorage
Windows	In the roaming AppData directory	In the roaming AppData directory

2.5.5

• Fixes dartdoc comments that accidentally used HTML.

2.5.4

• Updates dependencies for the shared_preferences_tool DevTools extension and fixes related deprecations.
• Updates minimum supported SDK version to Flutter 3.35/Dart 3.9.
• Updates README to reflect currently supported OS versions for the latest versions of the endorsed platform implementations.
  • Applications built with older versions of Flutter will continue to use compatible versions of the platform implementations.

2.5.3

• Fixes a bug in the example app.

2.5.2

• Fixes setState returning Future on example/main.dart error in example code.

2.5.1

• Exposes SharedPreferencesOptions.

2.5.0

• Adds shared preferences devtools extension.

2.4.0

• Adds migration tool to move from legacy SharedPreferences to SharedPreferencesAsync.
• Adds clarifying comment about allowList handling with an updated prefix.

2.3.5

• Adds information about Android SharedPreferences support.

2.3.4

• Security update, requires shared_preferences_android to be 2.3.4.

2.3.3

• Clarifies scope of prefix handling in README.

2.3.2

• Removes outdated testing information from README.
• Updates minimum supported SDK version to Flutter 3.22/Dart 3.4.

2.3.1

• Fixes getStringList bug with List<Object?> cast exception.

2.3.0

• Adds SharedPreferencesAsync and SharedPreferencesWithCache APIs.
• Updates minimum supported SDK version to Flutter 3.16/Dart 3.2.

2.2.3

• Updates minimum supported SDK version to Flutter 3.13/Dart 3.1.
• Updates support matrix in README to indicate that iOS 11 is no longer supported.
• Clients on versions of Flutter that still support iOS 11 can continue to use this package with iOS 11, but will not receive any further updates to the iOS implementation.
• Updates minimum supported SDK version to Flutter 3.10/Dart 3.0.
• Updates minimum iOS implementation version to include a privacy manifest.

2.2.2

• Updates documentation for containsKey.

2.2.1

• Adds pub topics to package metadata.
• Updates minimum supported SDK version to Flutter 3.7/Dart 2.19.
• Fixes the example app to be debuggable on Android.
• Deletes deprecated splash screen meta-data element.

2.2.0

• Adds allowList option to setPrefix.

2.1.2

• Fixes singleton initialization race condition introduced during NNBD transition.
• Updates minimum supported macOS version to 10.14.
• Updates minimum supported SDK version to Flutter 3.3/Dart 2.18.

2.1.1

• Updates iOS minimum version in README.

2.1.0

• Adds setPrefix method.

2.0.20

• Adds README discussion of reload().

2.0.19

• Updates README to use code excerpts.
• Aligns Dart and Flutter SDK constraints.

2.0.18

• Updates links for the merge of flutter/plugins into flutter/packages.
• Updates minimum Flutter version to 3.0.

2.0.17

• Updates code for stricter lint checks.

2.0.16

• Switches to the new shared_preferences_foundation implementation package for iOS and macOS.
• Updates code for no_leading_underscores_for_local_identifiers lint.
• Updates minimum Flutter version to 2.10.

2.0.15

• Minor fixes for new analysis options.

2.0.14

• Adds OS version support information to README.
• Fixes library_private_types_in_public_api, sort_child_properties_last and use_key_in_widget_constructors lint warnings.

2.0.13

• Updates documentation on README.md.

2.0.12

• Removes dependency on meta.

2.0.11

• Corrects example for mocking in readme.

2.0.10

• Removes obsolete manual registration of Windows and Linux implementations.

2.0.9

• Fixes newly enabled analyzer options.
• Updates example app Android compileSdkVersion to 31.
• Moved Android and iOS implementations to federated packages.

2.0.8

• Update minimum Flutter SDK to 2.5 and iOS deployment target to 9.0.

2.0.7

• Add iOS unit test target.
• Updated Android lint settings.
• Fix string clash with double entries on Android

2.0.6

• Migrate maven repository from jcenter to mavenCentral.

2.0.5

• Fix missing declaration of windows' default_package

2.0.4

• Fix a regression with simultaneous writes on Android.

2.0.3

• Android: don't create additional Handler when method channel is called.

2.0.2

• Don't create additional thread pools when method channel is called.

2.0.1

• Removed deprecated AsyncTask was deprecated in API level 30 (#3481)

2.0.0

• Migrate to null-safety.

Breaking changes:

• Setters no longer accept null to mean removing values. If you were previously using set*(key, null) for removing, use remove(key) instead.

0.5.13+2

• Fix outdated links across a number of markdown files (#3276)

0.5.13+1

• Update Flutter SDK constraint.

0.5.13

• Update integration test examples to use testWidgets instead of test.

0.5.12+4

• Remove unused test dependency.

0.5.12+3

• Check in windows/ directory for example/

0.5.12+2

• Update android compileSdkVersion to 29.

0.5.12+1

• Check in linux/ directory for example/

0.5.12

• Keep handling deprecated Android v1 classes for backward compatibility.

0.5.11

• Support Windows by default.

0.5.10

• Update package:e2e -> package:integration_test

0.5.9

• Update package:e2e reference to use the local version in the flutter/plugins repository.

0.5.8

• Support Linux by default.

0.5.7+3

• Post-v2 Android embedding cleanup.

0.5.7+2

• Update lower bound of dart dependency to 2.1.0.

0.5.7+1

• Declare API stability and compatibility with 1.0.0 (more details at: https://github.com/flutter/flutter/wiki/Package-migration-to-1.0.0).

0.5.7

• Remove Android dependencies fallback.
• Require Flutter SDK 1.12.13+hotfix.5 or greater.
• Fix CocoaPods podspec lint warnings.

0.5.6+3

• Fix deprecated API usage warning.

0.5.6+2

• Make the pedantic dev_dependency explicit.

0.5.6+1

• Updated README

0.5.6

• Support web by default.
• Require Flutter SDK 1.12.13+hotfix.4 or greater.

0.5.5

• Support macos by default.

0.5.4+10

• Adds a shared_preferences_macos package.

0.5.4+9

• Remove the deprecated author: field from pubspec.yaml
• Migrate the plugin to the pubspec platforms manifest.
• Require Flutter SDK 1.10.0 or greater.

0.5.4+8

• Switch package:shared_preferences to package:shared_preferences_platform_interface. No code changes are necessary in Flutter apps. This is not a breaking change.

0.5.4+7

• Restructure the project for Web support.

0.5.4+6

• Add missing documentation and a lint to prevent further undocumented APIs.

0.5.4+5

• Update and migrate iOS example project by removing flutter_assets, change "English" to "en", remove extraneous xcconfigs and framework outputs, update to Xcode 11 build settings, and remove ARCHS.

0.5.4+4

• setMockInitialValues needs to handle non-prefixed keys since that's an implementation detail.

0.5.4+3

• Android: Suppress casting warnings.

0.5.4+2

• Remove AndroidX warnings.

0.5.4+1

• Include lifecycle dependency as a compileOnly one on Android to resolve potential version conflicts with other transitive libraries.

0.5.4

• Support the v2 Android embedding.
• Update to AndroidX.
• Migrate to using the new e2e test binding.

0.5.3+5

• Define clang module for iOS.

0.5.3+4

• Copy List instances when reading and writing values to prevent mutations from propagating.

0.5.3+3

• setMockInitialValues can now be called multiple times and will reload() the singleton if necessary.

0.5.3+2

• Fix Gradle version.

0.5.3+1

• Add missing template type parameter to invokeMethod calls.
• Bump minimum Flutter version to 1.5.0.
• Replace invokeMethod with invokeMapMethod wherever necessary.

0.5.3

• Add reload method.

0.5.2+2

• Updated Gradle tooling to match Android Studio 3.4.

0.5.2+1

• .commit() calls are now run in an async background task on Android.

0.5.2

• Add containsKey method.

0.5.1+2

• Add a driver test

0.5.1+1

• Log a more detailed warning at build time about the previous AndroidX migration.

0.5.1

• Use String to save double in Android.

0.5.0

• Breaking change. Migrate from the deprecated original Android Support Library to AndroidX. This shouldn't result in any functional changes, but it requires any Android apps using this plugin to also migrate if they're using the original support library.

0.4.3

• Prevent strings that match special prefixes from being saved. This is a bugfix that prevents apps from accidentally setting special values that would be interpreted incorrectly.

0.4.2

• Updated Gradle tooling to match Android Studio 3.1.2.

0.4.1

• Added getKeys method.

0.4.0

• Breaking change. Set SDK constraints to match the Flutter beta release.

0.3.3

• Fixed Dart 2 issues.

0.3.2

• Added an getter that can retrieve values of any type

0.3.1

• Simplified and upgraded Android project template to Android SDK 27.
• Updated package description.

0.3.0

• Breaking change. Upgraded to Gradle 4.1 and Android Studio Gradle plugin 3.0.1. Older Flutter projects need to upgrade their Gradle setup as well in order to use this version of the plugin. Instructions can be found here.

0.2.6

• Added FLT prefix to iOS types

0.2.5+1

• Aligned author name with rest of repo.

0.2.5

• Fixed crashes when setting null values. They now cause the key to be removed.
• Added remove() method

0.2.4+1

• Fixed typo in changelog

0.2.4

• Added setMockInitialValues
• Added a test
• Updated README

0.2.3

• Suppress warning about unchecked operations when compiling for Android

0.2.2

• BREAKING CHANGE: setStringSet API changed to setStringList and plugin now supports ordered storage.

0.2.1

• Support arbitrary length integers for setInt.

0.2.0+1

• Updated README

0.2.0

• Upgrade to new plugin registration. (https://groups.google.com/forum/#!topic/flutter-dev/zba1Ynf2OKM)

0.1.1

• Upgrade Android SDK Build Tools to 25.0.3.

0.1.0

• Initial Open Source release.