Have ideas to improve npm?Join in the discussion! »

    @capacitor/storage
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    @capacitor/storage

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

    Mobile OS's 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' });
    
      alert(`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(...)

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

    Configure the storage 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 storage 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 storage for a given key.

    Param Type
    options SetOptions

    Since: 1.0.0


    remove(...)

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

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

    Param Type
    options RemoveOptions

    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.

    Returns: Promise<MigrateResult>

    Since: 1.0.0


    Interfaces

    ConfigureOptions

    Prop Type Description Default Since
    group string Set the storage group. Storage 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 storage 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 storage. 1.0.0

    SetOptions

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

    RemoveOptions

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

    KeysResult

    Prop Type Description Since
    keys string[] The known keys in storage. 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 storage that had a value in the Capacitor 2 Storage plugin. 1.0.0

    Install

    npm i @capacitor/storage

    DownloadsWeekly Downloads

    7,609

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    64.2 kB

    Total Files

    29

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar