@capacitor/storage

The Storage 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/storage
npx cap sync

Example

import { Storage } from '@capacitor/storage';

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

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

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

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

Working with JSON

The Storage 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(...)
• get(...)
• set(...)
• remove(...)
• clear()
• keys()
• migrate()
• removeOld()
• Interfaces

configure(...)

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

Configure the storage plugin at runtime.

Options that are undefined will not be used.

Since: 1.0.0

get(...)

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

Get the value from storage of a given key.

Returns: Promise<GetResult>

Since: 1.0.0

set(...)

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

Set the value in storage for a given key.

Since: 1.0.0

remove(...)

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

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

Since: 1.0.0

clear()

clear() => Promise<void>

Clear keys and values from storage.

Since: 1.0.0

keys()

keys() => Promise<KeysResult>

Return the list of known keys in storage.

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

GetResult

GetOptions

SetOptions

RemoveOptions

KeysResult

MigrateResult