Choose a version:

Storage
API

The API for interacting with local storage.

Anchor to standardapiStandardApi

The base API object provided to purchase extension targets.

Anchor to storage storage required: The key-value storage for the extension.

It uses localStorage and should persist across the customer's current checkout session.

Caution
Data persistence isn't guaranteed and storage is reset when the customer starts a new checkout.
Data is shared across all activated extension targets of this extension. In versions 2023-07 and earlier, each activated extension target had its own storage.

Docs_Standard_StorageApi

storage
The key-value storage for the extension. It uses `localStorage` and should persist across the customer's current checkout session. > Caution: Data persistence isn't guaranteed and storage is reset when the customer starts a new checkout. Data is shared across all activated extension targets of this extension. In versions 2023-07 and earlier, each activated extension target had its own storage.
```
Storage
```

export interface Docs_Standard_StorageApi
  extends Pick<StandardApi, 'storage'> {}

Storage

A key-value storage object for the extension. Stored data is only available to this specific extension and any of its instances. The storage backend is implemented with `localStorage` and should persist across the buyer's checkout session. However, data persistence isn't guaranteed.

delete
Delete stored data by key.
```
(key: string) => Promise<void>
```
read
Read and return a stored value by key. The stored data is deserialized from JSON and returned as its original primitive. Returns `null` if no stored data exists.
```
<T = unknown>(key: string) => Promise<T>
```
write
Write stored data for this key. The data must be serializable to JSON.
```
(key: string, data: any) => Promise<void>
```

export interface Storage {
  /**
   * Read and return a stored value by key.
   *
   * The stored data is deserialized from JSON and returned as
   * its original primitive.
   *
   * Returns `null` if no stored data exists.
   */
  read<T = unknown>(key: string): Promise<T | null>;

  /**
   * Write stored data for this key.
   *
   * The data must be serializable to JSON.
   */
  write(key: string, data: any): Promise<void>;

  /**
   * Delete stored data by key.
   */
  delete(key: string): Promise<void>;
}

Was this section helpful?

Anchor to useStorage
useStorage()

Returns the key-value Storage interface for the extension target.

Anchor to useStorage-returnsReturns

Storage

delete (key: string) => Promise<void>: Delete stored data by key.
read <T = unknown>(key: string) => Promise<T>: Read and return a stored value by key.

The stored data is deserialized from JSON and returned as its original primitive.

Returns null if no stored data exists.
write (key: string, data: any) => Promise<void>: Write stored data for this key.

The data must be serializable to JSON.

UseStorageGeneratedType

Returns the key-value `Storage` interface for the extension. Uses `localStorage` and should persist across the buyer's current checkout session. However, data persistence isn't guaranteed and storage is reset when the buyer starts a new checkout. Data is shared across all activated extension targets of this extension. In versions `<=2023-07`, each activated extension target had its own storage.

Storage

Storage

export function useStorage<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): Storage {
  return useApi<Target>().storage;
}

Storage

delete
Delete stored data by key.
```
(key: string) => Promise<void>
```
read
Read and return a stored value by key. The stored data is deserialized from JSON and returned as its original primitive. Returns `null` if no stored data exists.
```
<T = unknown>(key: string) => Promise<T>
```
write
Write stored data for this key. The data must be serializable to JSON.
```
(key: string, data: any) => Promise<void>
```

export interface Storage {
  /**
   * Read and return a stored value by key.
   *
   * The stored data is deserialized from JSON and returned as
   * its original primitive.
   *
   * Returns `null` if no stored data exists.
   */
  read<T = unknown>(key: string): Promise<T | null>;

  /**
   * Write stored data for this key.
   *
   * The data must be serializable to JSON.
   */
  write(key: string, data: any): Promise<void>;

  /**
   * Delete stored data by key.
   */
  delete(key: string): Promise<void>;
}

Was this section helpful?

Storage

React

import {useEffect, useState} from 'react';

import {

reactExtension,

Checkbox,

useApi,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

const {storage} = useApi();

const [tosConsent, setTosConsent] =

useState(false);

useEffect(() => {

async function readFromStorage() {

const tosConsent = await storage.read(

'tos-consent',

);

setTosConsent(Boolean(tosConsent));

}

readFromStorage();

}, [storage]);

async function cacheConsent(value: boolean) {

setTosConsent(value);

await storage.write('tos-consent', value);

}

return (

<Checkbox

id="tos"

name="tos"

onChange={cacheConsent}

checked={tosConsent}

I agree with the terms of service

</Checkbox>

);

}

examples

Storage

React

import {useEffect, useState} from 'react';
import {
  reactExtension,
  Checkbox,
  useApi,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const {storage} = useApi();
  const [tosConsent, setTosConsent] =
    useState(false);

  useEffect(() => {
    async function readFromStorage() {
      const tosConsent = await storage.read(
        'tos-consent',
      );

      setTosConsent(Boolean(tosConsent));
    }

    readFromStorage();
  }, [storage]);

  async function cacheConsent(value: boolean) {
    setTosConsent(value);
    await storage.write('tos-consent', value);
  }

  return (
    <Checkbox
      id="tos"
      name="tos"
      onChange={cacheConsent}
      checked={tosConsent}
    >
      I agree with the terms of service
    </Checkbox>
  );
}