Skip to main content
Version: v5

@capacitor/preferences

The Preferences API provides a simple key/value persistent store for lightweight data.

Mobile OSs may periodically clear data set in window.localStorage, so this API should be used instead. This API will fall back to using localStorage when running as a Progressive Web App.

This plugin will use UserDefaults on iOS and SharedPreferences on Android. Stored data is cleared if the app is uninstalled.

Note: This API is not meant to be used as a local database. If your app stores a lot of data, has high read/write load, or requires complex querying, we recommend taking a look at a SQLite-based solution. One such solution is Ionic Secure Storage, a SQLite-based engine with full encryption support. The Capacitor Community has also built a number of other storage engines.

Installโ€‹

npm install @capacitor/preferences
npx cap sync

Exampleโ€‹

import { Preferences } from '@capacitor/preferences';

const setName = async () => {
await Preferences.set({
key: 'name',
value: 'Max',
});
};

const checkName = async () => {
const { value } = await Preferences.get({ key: 'name' });

console.log(`Hello ${value}!`);
};

const removeName = async () => {
await Preferences.remove({ key: 'name' });
};

Working with JSONโ€‹

The Preferences API only supports string values. You can, however, use JSON if you JSON.stringify the object before calling set(), then JSON.parse the value returned from get().

This method can also be used to store non-string values, such as numbers and booleans.

APIโ€‹

configure(...)โ€‹

configure(options: ConfigureOptions) => Promise<void>

Configure the preferences plugin at runtime.

Options that are undefined will not be used.

Param Type
options
ConfigureOptions

Since: 1.0.0


get(...)โ€‹

get(options: GetOptions) => Promise<GetResult>

Get the value from preferences of a given key.

Param Type
options
GetOptions

Returns:

Promise<GetResult>

Since: 1.0.0


set(...)โ€‹

set(options: SetOptions) => Promise<void>

Set the value in preferences for a given key.

Param Type
options
SetOptions

Since: 1.0.0


remove(...)โ€‹

remove(options: RemoveOptions) => Promise<void>

Remove the value from preferences for a given key, if any.

Param Type
options
RemoveOptions

Since: 1.0.0


clear()โ€‹

clear() => Promise<void>

Clear keys and values from preferences.

Since: 1.0.0


keys()โ€‹

keys() => Promise<KeysResult>

Return the list of known keys in preferences.

Returns:

Promise<KeysResult>

Since: 1.0.0


migrate()โ€‹

migrate() => Promise<MigrateResult>

Migrate data from the Capacitor 2 Storage plugin.

This action is non-destructive. It will not remove old data and will only write new data if they key was not already set. To remove the old data after being migrated, call removeOld().

Returns:

Promise<MigrateResult>

Since: 1.0.0


removeOld()โ€‹

removeOld() => Promise<void>

Removes old data with _cap_ prefix from the Capacitor 2 Storage plugin.

Since: 1.1.0


Interfacesโ€‹

ConfigureOptionsโ€‹

Prop Type Description Default Since
group string Set the preferences group. Preferences groups are used to organize key/value pairs. Using the value 'NativeStorage' provides backwards-compatibility with cordova-plugin-nativestorage. WARNING: The clear() method can delete unintended values when using the 'NativeStorage' group. CapacitorStorage 1.0.0

GetResultโ€‹

Prop Type Description Since
value string | null The value from preferences associated with the given key. If a value was not previously set or was removed, value will be null. 1.0.0

GetOptionsโ€‹

Prop Type Description Since
key string The key whose value to retrieve from preferences. 1.0.0

SetOptionsโ€‹

Prop Type Description Since
key string The key to associate with the value being set in preferences. 1.0.0
value string The value to set in preferences with the associated key. 1.0.0

RemoveOptionsโ€‹

Prop Type Description Since
key string The key whose value to remove from preferences. 1.0.0

KeysResultโ€‹

Prop Type Description Since
keys string[] The known keys in preferences. 1.0.0

MigrateResultโ€‹

Prop Type Description Since
migrated string[] An array of keys that were migrated. 1.0.0
existing string[] An array of keys that were already migrated or otherwise exist in preferences that had a value in the Capacitor 2 Preferences plugin. 1.0.0