useStorage

browser

Installation

npx usehooks-cli@latest add use-storage

Description

A React hook for managing browser storage quotas and persistence using the Storage API. Provides storage estimation, usage monitoring, and persistent storage management.

Return Type

UseStorageReturn

Property	Type	Description
estimate	StorageEstimate \| null	Current storage quota and usage information
isLoading	boolean	True when fetching storage information
error	string \| null	Error message if storage operations fail
isPersistent	boolean \| null	Whether storage is persistent (won't be cleared under pressure)
usagePercentage	number \| null	Percentage of storage quota currently used
isSupported	boolean	Whether the Storage API is supported in this browser
getEstimate	() => Promise<StorageEstimate \| null>	Manually refresh storage estimate
requestPersistentStorage	() => Promise<boolean>	Request persistent storage permission from the browser
checkPersistence	() => Promise<boolean>	Check if storage is currently persistent

Examples

Storage Usage Monitor

Displaying current storage usage and quota information

const { 
  estimate, 
  usagePercentage, 
  isLoading, 
  error, 
  isSupported 
} = useStorage();

if (!isSupported) {
  return <div>Storage API not supported</div>;
}

if (isLoading) {
  return <div>Loading storage info...</div>;
}

if (error) {
  return <div>Error: {error}</div>;
}

return (
  <div className="storage-info">
    <h3>Storage Usage</h3>
    {estimate && (
      <>
        <div className="usage-bar">
          <div 
            className="usage-fill"
            style={{ width: `${usagePercentage}%` }}
          />
        </div>
        <p>
          Used: {(estimate.usage / 1024 / 1024).toFixed(2)} MB of{' '}
          {(estimate.quota / 1024 / 1024).toFixed(2)} MB
          ({usagePercentage}%)
        </p>
        {estimate.usageDetails && (
          <div className="usage-details">
            <h4>Usage by type:</h4>
            {Object.entries(estimate.usageDetails).map(([key, value]) => (
              <p key={key}>
                {key}: {(value / 1024 / 1024).toFixed(2)} MB
              </p>
            ))}
          </div>
        )}
      </>
    )}
  </div>
);

Persistent Storage Manager

Managing persistent storage permissions and status

const { 
  isPersistent, 
  requestPersistentStorage, 
  checkPersistence,
  error 
} = useStorage();
const [isRequesting, setIsRequesting] = useState(false);

const handleRequestPersistent = async () => {
  setIsRequesting(true);
  try {
    const granted = await requestPersistentStorage();
    if (granted) {
      showToast('Persistent storage granted!');
    } else {
      showToast('Persistent storage denied');
    }
  } catch (err) {
    showToast('Failed to request persistent storage');
  } finally {
    setIsRequesting(false);
  }
};

const handleCheckPersistence = async () => {
  await checkPersistence();
};

return (
  <div className="persistence-manager">
    <h3>Storage Persistence</h3>
    
    <div className="status">
      Status: {
        isPersistent === null ? 'Unknown' :
        isPersistent ? '✅ Persistent' : '⚠️ Not Persistent'
      }
    </div>
    
    {!isPersistent && (
      <div className="warning">
        <p>Your data may be cleared when storage is low.</p>
        <button 
          onClick={handleRequestPersistent}
          disabled={isRequesting}
        >
          {isRequesting ? 'Requesting...' : 'Request Persistent Storage'}
        </button>
      </div>
    )}
    
    <button onClick={handleCheckPersistence}>
      Refresh Status
    </button>
    
    {error && <div className="error">{error}</div>}
  </div>
);

Storage Quota Warning

Warning users when storage is running low

const { 
  estimate, 
  usagePercentage, 
  getEstimate,
  requestPersistentStorage 
} = useStorage();
const [showWarning, setShowWarning] = useState(false);

// Check storage usage periodically
useEffect(() => {
  const interval = setInterval(() => {
    getEstimate();
  }, 60000); // Check every minute

  return () => clearInterval(interval);
}, [getEstimate]);

// Show warning when storage is getting full
useEffect(() => {
  if (usagePercentage && usagePercentage > 80) {
    setShowWarning(true);
  } else {
    setShowWarning(false);
  }
}, [usagePercentage]);

const handleClearCache = async () => {
  // Clear application cache
  await clearApplicationCache();
  await getEstimate(); // Refresh storage info
  showToast('Cache cleared successfully');
};

return (
  <div>
    {showWarning && (
      <div className="storage-warning">
        <h4>⚠️ Storage Running Low</h4>
        <p>
          You're using {usagePercentage}% of your available storage.
          Consider clearing some data or requesting persistent storage.
        </p>
        <div className="warning-actions">
          <button onClick={handleClearCache}>
            Clear Cache
          </button>
          <button onClick={requestPersistentStorage}>
            Request Persistent Storage
          </button>
        </div>
      </div>
    )}
    
    {/* Rest of your app */}
  </div>
);

Dependencies

react

Notes

•Requires a modern browser with Storage API support
•Automatically fetches storage estimate and persistence status on mount
•Persistent storage prevents data from being cleared under storage pressure
•Storage estimates are approximate and may vary between browsers
•Useful for PWAs and applications that store significant amounts of data
•Provides both automatic monitoring and manual control methods

Implementation

'use client';

import { useState, useEffect, useCallback } from "react";

interface StorageEstimate {
  quota?: number;
  usage?: number;
  usageDetails?: {
    [key: string]: number;
  };
}

interface UseStorageReturn {
  // Storage estimation
  estimate: StorageEstimate | null;
  isLoading: boolean;
  error: string | null;

  // Persistence management
  isPersistent: boolean | null;

  // Methods
  getEstimate: () => Promise<StorageEstimate | null>;
  requestPersistentStorage: () => Promise<boolean>;
  checkPersistence: () => Promise<boolean>;

  // Computed values
  usagePercentage: number | null;
  isSupported: boolean;
}

export const useStorage = (): UseStorageReturn => {
  const [estimate, setEstimate] = useState<StorageEstimate | null>(null);
  const [isPersistent, setIsPersistent] = useState<boolean | null>(null);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  // Check if Storage API is supported
  const isSupported =
    typeof navigator !== "undefined" &&
    "storage" in navigator &&
    typeof navigator.storage.estimate === "function";

  // Get storage estimate
  const getEstimate = useCallback(async (): Promise<StorageEstimate | null> => {
    if (!isSupported) {
      setError("Storage API is not supported");
      return null;
    }

    try {
      setIsLoading(true);
      setError(null);

      const storageEstimate = await navigator.storage.estimate();
      setEstimate(storageEstimate);
      return storageEstimate;
    } catch (err) {
      const errorMessage =
        err instanceof Error ? err.message : "Failed to get storage estimate";
      setError(errorMessage);
      return null;
    } finally {
      setIsLoading(false);
    }
  }, [isSupported]);

  // Request persistent storage
  const requestPersistentStorage = useCallback(async (): Promise<boolean> => {
    if (!isSupported || !navigator.storage.persist) {
      setError("Persistent storage is not supported");
      return false;
    }

    try {
      setError(null);
      const persistent = await navigator.storage.persist();
      setIsPersistent(persistent);
      return persistent;
    } catch (err) {
      const errorMessage =
        err instanceof Error
          ? err.message
          : "Failed to request persistent storage";
      setError(errorMessage);
      return false;
    }
  }, [isSupported]);

  // Check if storage is persistent
  const checkPersistence = useCallback(async (): Promise<boolean> => {
    if (!isSupported || !navigator.storage.persisted) {
      setError("Persistence check is not supported");
      return false;
    }

    try {
      setError(null);
      const persistent = await navigator.storage.persisted();
      setIsPersistent(persistent);
      return persistent;
    } catch (err) {
      const errorMessage =
        err instanceof Error ? err.message : "Failed to check persistence";
      setError(errorMessage);
      return false;
    }
  }, [isSupported]);

  // Calculate usage percentage
  const usagePercentage =
    estimate?.quota && estimate?.usage
      ? Math.round((estimate.usage / estimate.quota) * 100)
      : null;

  // Initialize on mount
  useEffect(() => {
    if (isSupported) {
      getEstimate();
      checkPersistence();
    }
  }, [isSupported, getEstimate, checkPersistence]);

  return {
    estimate,
    isLoading,
    error,
    isPersistent,
    getEstimate,
    requestPersistentStorage,
    checkPersistence,
    usagePercentage,
    isSupported,
  };
};

useContactPicker

CLI Docs All Hooks

useWebShare