@stripe/ui-extension-sdk/data/useStorage.d.ts

The suite of functionality available to UI extensions in Stripe apps

/**
 * Hook for reading and writing shared data across different viewports of a Stripe App.
 *
 * Provides a way to synchronize state between all active instances
 * (viewports) of your Stripe App within the same browser context. When the
 * value is updated in one instance, all other instances in the same browser
 * will reflect the change automatically. This is session-based storage that
 * exists only while the app is running.
 *
 * Accepts a unique identifier for the storage item.
 *
 * Returns a tuple containing the current value from storage and a function to
 * update the value in storage.
 *
 * Potential use cases:
 * - Coordinating state between multiple viewports of your app
 * - Avoiding redundant API calls by caching and sharing fetched data across viewports.
 *
 * Example:
 * ```tsx
 * // Share state across viewports
 * const [currentTab, setCurrentTab] = useStorage('activeTab');
 *
 * // Update the shared value
 * const handleTabChange = (tabName) => {
 *   setCurrentTab(tabName);
 * };
 *
 * // All viewports will display the same tab
 * return <Box>Active tab: {currentTab || 'home'}</Box>;
 * ```
 *
 * Please note that
 * - Values are limited to strings. For complex objects, please use JSON.stringify/parse.
 * - Storage is not persistent between app sessions.
 * - Changes won't synchronize between different browsers or devices.
 *
 * See: https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api#useStorage
 */
export declare function useStorage(key: string): [string | null, (value: string) => void];