Shared Preferences

https://pub.dev/packages/shared_preferences
Admin
A Flutter plugin that wraps platform-specific persistent storage for reading and writing simple...
Tokens:13,878
Snippets:182
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### SharedPreferencesAsync example

Source: https://pub.dev/packages/shared_preferences

Demonstrates using the async variant of SharedPreferences. It shows setting, getting, removing, and clearing with an allowList to avoid unwanted side effects.

```dart
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 example

Source: https://pub.dev/packages/shared_preferences

Demonstrates using SharedPreferencesWithCache with an allowList configured at creation. It shows setting, getting, removing, and clearing without needing filter options during clear.

```dart
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();
```

--------------------------------

### Example main.dart for shared_preferences_foundation

Source: https://pub.dev/packages/shared_preferences_foundation/example

Complete Flutter example app demonstrating the use of SharedPreferencesAsyncPlatform and SharedPreferencesAsyncFoundationOptions. It reads and writes an integer counter using getInt and setInt, and displays the value with a FutureBuilder. The code includes error handling and a floating action button to increment the counter.

```Dart
// Copyright 2013 The Flutter Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// ignore_for_file: public_member_api_docs

import 'package:flutter/material.dart';
import 'package:shared_preferences_foundation/shared_preferences_foundation.dart';
import 'package:shared_preferences_platform_interface/shared_preferences_async_platform_interface.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(title: 'SharedPreferences Demo', home: SharedPreferencesDemo());
  }
}

class SharedPreferencesDemo extends StatefulWidget {
  const SharedPreferencesDemo({super.key});

  @override
  SharedPreferencesDemoState createState() => SharedPreferencesDemoState();
}

class SharedPreferencesDemoState extends State<SharedPreferencesDemo> {
  final SharedPreferencesAsyncPlatform? _prefs = SharedPreferencesAsyncPlatform.instance;
  SharedPreferencesAsyncFoundationOptions options = SharedPreferencesAsyncFoundationOptions();
  static const String _counterKey = 'counter';
  late Future<int> _counter;

  Future<void> _incrementCounter() async {
    final int? value = await _prefs!.getInt(_counterKey, options);
    final int counter = (value ?? 0) + 1;

    setState(() {
      _counter = _prefs.setInt(_counterKey, counter, options).then((_) {
        return counter;
      });
    });
  }

  Future<void> _getAndSetCounter() async {
    setState(() {
      _counter = _prefs!.getInt(_counterKey, options).then((int? counter) {
        return counter ?? 0;
      });
    });
  }

  @override
  void initState() {
    super.initState();
    _getAndSetCounter();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('SharedPreferences Demo')),
      body: Center(
        child: FutureBuilder<int>(
          future: _counter,
          builder: (BuildContext context, AsyncSnapshot<int> snapshot) {
            switch (snapshot.connectionState) {
              case ConnectionState.none:
              case ConnectionState.waiting:
                return const CircularProgressIndicator();
              case ConnectionState.active:
              case ConnectionState.done:
                if (snapshot.hasError) {
                  return Text('Error: ${snapshot.error}');
                } else {
                  return Text(
                    'Button tapped ${snapshot.data} time${snapshot.data == 1 ? '' : 's'}.\n\n'
                    'This should persist across restarts.',
                  );
                }
            }
          },
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

```

--------------------------------

### Example: main.dart using SharedPreferencesAsyncAndroidOptions

Source: https://pub.dev/packages/shared_preferences_android/example

Complete example app that uses SharedPreferencesAsyncPlatform to store and retrieve a counter value. It defines Android-specific options with a custom file name and uses the SharedPreferences backend.

```dart
// Copyright 2013 The Flutter Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// ignore_for_file: public_member_api_docs, unreachable_from_main

import 'package:flutter/material.dart';
import 'package:shared_preferences_android/shared_preferences_android.dart';
import 'package:shared_preferences_platform_interface/shared_preferences_async_platform_interface.dart';

void main() {
  runApp(const MyApp());
}

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

// #enddocregion Android_Options

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(title: 'SharedPreferences Demo', home: SharedPreferencesDemo());
  }
}

class SharedPreferencesDemo extends StatefulWidget {
  const SharedPreferencesDemo({super.key});

  @override
  SharedPreferencesDemoState createState() => SharedPreferencesDemoState();
}

class SharedPreferencesDemoState extends State<SharedPreferencesDemo> {
  final SharedPreferencesAsyncPlatform _prefs = SharedPreferencesAsyncPlatform.instance!;
  final SharedPreferencesAsyncAndroidOptions options = const SharedPreferencesAsyncAndroidOptions();
  static const String _counterKey = 'counter';
  late Future<int> _counter;

  Future<void> _incrementCounter() async {
    final int? value = await _prefs.getInt(_counterKey, options);
    final int counter = (value ?? 0) + 1;

    setState(() {
      _counter = _prefs.setInt(_counterKey, counter, options).then((_) {
        return counter;
      });
    });
  }

  Future<void> _getAndSetCounter() async {
    setState(() {
      _counter = _prefs.getInt(_counterKey, options).then((int? counter) {
        return counter ?? 0;
      });
    });
  }

  @override
  void initState() {
    super.initState();
    _getAndSetCounter();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('SharedPreferences Demo')),
      body: Center(
        child: FutureBuilder<int>(
          future: _counter,
          builder: (BuildContext context, AsyncSnapshot<int> snapshot) {
            switch (snapshot.connectionState) {
              case ConnectionState.none:
              case ConnectionState.waiting:
                return const CircularProgressIndicator();
              case ConnectionState.active:
              case ConnectionState.done:
                if (snapshot.hasError) {
                  return Text('Error: ${snapshot.error}');
                } else {
                  return Text(
                    'Button tapped ${snapshot.data} time${snapshot.data == 1 ? '' : 's'}.\n\n'
                    'This should persist across restarts.',
                  );
                }
            }
          },
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

```

--------------------------------

### Full example app for shared_preferences (main.dart)

Source: https://pub.dev/packages/shared_preferences/example

Complete Flutter app demonstrating the shared_preferences plugin. It uses SharedPreferencesWithCache with an allowlist for the 'counter' key, SharedPreferencesAsync for external counters, and migrates legacy preferences using migrateLegacySharedPreferencesToSharedPreferencesAsyncIfNecessary. The app shows a counter that persists across restarts and waits for migration before rendering.

```dart
// Copyright 2013 The Flutter Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// ignore_for_file: public_member_api_docs

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';
// #docregion migrate
import 'package:shared_preferences/util/legacy_to_async_migration_util.dart';

// #enddocregion migrate

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      title: 'SharedPreferencesWithCache Demo',
      home: SharedPreferencesDemo(),
    );
  }
}

class SharedPreferencesDemo extends StatefulWidget {
  const SharedPreferencesDemo({super.key});

  @override
  SharedPreferencesDemoState createState() => SharedPreferencesDemoState();
}

class SharedPreferencesDemoState extends State<SharedPreferencesDemo> {
  final Future<SharedPreferencesWithCache> _prefs = SharedPreferencesWithCache.create(
    cacheOptions: const SharedPreferencesWithCacheOptions(
      // This cache will only accept the key 'counter'.
      allowList: <String>{'counter'},
    ),
  );
  late Future<int> _counter;
  int _externalCounter = 0;

  /// Completes when the preferences have been initialized, which happens after
  /// legacy preferences have been migrated.
  final Completer<void> _preferencesReady = Completer<void>();

  Future<void> _incrementCounter() async {
    final SharedPreferencesWithCache prefs = await _prefs;
    final int counter = (prefs.getInt('counter') ?? 0) + 1;

    setState(() {
      _counter = prefs.setInt('counter', counter).then((_) {
        return counter;
      });
    });
  }

  /// Gets external button presses that could occur in another instance, thread,
  /// or via some native system.
  Future<void> _getExternalCounter() async {
    final prefs = SharedPreferencesAsync();
    final int externalCounter = (await prefs.getInt('externalCounter')) ?? 0;
    setState(() {
      _externalCounter = externalCounter;
    });
  }

  Future<void> _migratePreferences() async {
    // #docregion migrate
    const sharedPreferencesOptions = SharedPreferencesOptions();
    final SharedPreferences prefs = await SharedPreferences.getInstance();
    await migrateLegacySharedPreferencesToSharedPreferencesAsyncIfNecessary(
      legacySharedPreferencesInstance: prefs,
      sharedPreferencesAsyncOptions: sharedPreferencesOptions,
      migrationCompletedKey: 'migrationCompleted',
    );
    // #enddocregion migrate
  }

  @override
  void initState() {
    super.initState();
    _migratePreferences().then((_) {
      _counter = _prefs.then((SharedPreferencesWithCache prefs) {
        return prefs.getInt('counter') ?? 0;
      });
      _getExternalCounter();
      _preferencesReady.complete();
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('SharedPreferencesWithCache Demo')),
      body: Center(
        child: _WaitForInitialization(
          initialized: _preferencesReady.future,
          builder: (BuildContext context) => FutureBuilder<int>(
            future: _counter,
            builder: (BuildContext context, AsyncSnapshot<int> snapshot) {
              switch (snapshot.connectionState) {
                case ConnectionState.none:
                case ConnectionState.waiting:
                  return const CircularProgressIndicator();
                case ConnectionState.active:
                case ConnectionState.done:
                  if (snapshot.hasError) {
                    return Text('Error: ${snapshot.error}');
                  } else {
                    return Text(
                      'Button tapped ${snapshot.data ?? 0 + _externalCounter} time${(snapshot.data ?? 0 + _externalCounter) == 1 ? '' : 's'}.\n\n'
                      'This should persist across restarts.',
                    );
                  }
              }
            },
          ),
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

/// Waits for the [initialized] future to complete before rendering [builder].
class _WaitForInitialization extends StatelessWidget {
  const _WaitForInitialization({required this.initialized, required this.builder});

  final Future<void> initialized;
  final WidgetBuilder builder;

```

--------------------------------

### Configure SharedPreferencesAsync with Android SharedPreferences backend

Source: https://pub.dev/packages/shared_preferences_android

Use SharedPreferencesAsyncAndroidOptions to select the Android SharedPreferences backend for the SharedPreferencesAsync API. The example sets the backend to SharedPreferencesAndroidBackendLibrary.SharedPreferences and specifies a file name for the AndroidSharedPreferencesStoreOptions.

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

--------------------------------

### Migrate from SharedPreferences to SharedPreferencesAsync

Source: https://pub.dev/packages/shared_preferences

Use this migration utility to transition from SharedPreferences to SharedPreferencesAsync. Provide the existing SharedPreferences instance and the new options, along with a migrationCompletedKey. Safe to run on every launch as long as the key is not altered or deleted.

```dart
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',
    );

```

--------------------------------

### Write data with SharedPreferences

Source: https://pub.dev/packages/shared_preferences

Shows how to obtain the SharedPreferences instance and save various data types (int, bool, double, String, and list of strings) to different keys. Use this to persist simple data.

```dart
// 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']);
```

--------------------------------

### Import shared_preferences_android

Source: https://pub.dev/packages/shared_preferences

Import the Android-specific package to use the SharedPreferencesAsyncAndroidOptions.

```dart
import 'package:shared_preferences_android/shared_preferences_android.dart';

```

--------------------------------

### Read data with SharedPreferences

Source: https://pub.dev/packages/shared_preferences

Shows how to read values from SharedPreferences using the same keys used for writing. Each getter returns null if the key does not exist.

```dart
// 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');
```

--------------------------------

### Configure SharedPreferencesAsyncAndroidOptions

Source: https://pub.dev/packages/shared_preferences

Define options to use the Android SharedPreferences backend with SharedPreferencesAsync, specifying the backend library and file name.

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

```

--------------------------------

### Build method with FutureBuilder for shared_preferences initialization

Source: https://pub.dev/packages/shared_preferences/example

Overrides the build method to show a CircularProgressIndicator while the shared_preferences initialization future is pending, then delegates to the provided builder once complete.

```dart
@override
  Widget build(BuildContext context) {
    return FutureBuilder<void>(
      future: initialized,
      builder: (BuildContext context, AsyncSnapshot<void> snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting ||
            snapshot.connectionState == ConnectionState.none) {
          return const CircularProgressIndicator();
        }
        return builder(context);
      },
    );
  }
}
```

--------------------------------

### Remove an entry with SharedPreferences

Source: https://pub.dev/packages/shared_preferences

Shows how to remove a stored value by its key using the remove method.

```dart
// Remove data for the 'counter' key.
await prefs.remove('counter');
```
Tokens:
Raw