useIndexedDB

state

Installation

npx usehooks-cli@latest add use-indexed-db

Description

A React hook for managing IndexedDB operations with automatic database initialization, error handling, and React state synchronization. IndexedDB is a low-level API for client-side storage of significant amounts of structured data.

Parameters

Name	Type	Default	Description
databaseName	string	-	The name of the IndexedDB database to open or create
storeName	string	-	The name of the object store within the database
options?	UseIndexedDBOptions	-	Optional configuration object

Return Type

UseIndexedDBReturn<T>

Property	Type	Description
data	T \| null	The most recently retrieved data from IndexedDB
error	string \| null	Error message if any operation failed
loading	boolean	Whether the database is currently being initialized
setItem	(key: string, value: T) => Promise<void>	Store a value in IndexedDB with the given key
getItem	(key: string) => Promise<T \| null>	Retrieve a value from IndexedDB by key
removeItem	(key: string) => Promise<void>	Remove a value from IndexedDB by key
clear	() => Promise<void>	Clear all data from the object store
getAllKeys	() => Promise<string[]>	Get all keys from the object store

Examples

Basic Usage

Simple key-value storage with IndexedDB

const { data, error, loading, setItem, getItem } = useIndexedDB('myApp', 'userData');

const saveUserData = async () => {
  try {
    await setItem('user-123', { name: 'John Doe', email: 'john@example.com' });
    console.log('User data saved!');
  } catch (err) {
    console.error('Failed to save:', err);
  }
};

const loadUserData = async () => {
  try {
    const userData = await getItem('user-123');
    console.log('Loaded user:', userData);
  } catch (err) {
    console.error('Failed to load:', err);
  }
};

if (loading) return <div>Initializing database...</div>;
if (error) return <div>Error: {error}</div>;

return (
  <div>
    <button onClick={saveUserData}>Save User Data</button>
    <button onClick={loadUserData}>Load User Data</button>
    {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
  </div>
);

Advanced Usage with Custom Schema

Using IndexedDB with custom database schema and upgrade handling

interface TodoItem {
  id: string;
  title: string;
  completed: boolean;
  createdAt: Date;
}

const { setItem, getItem, getAllKeys, clear } = useIndexedDB<TodoItem>(
  'todoApp',
  'todos',
  {
    version: 2,
    onUpgradeNeeded: (db, oldVersion, newVersion) => {
      if (oldVersion < 1) {
        // Create todos store
        const todosStore = db.createObjectStore('todos');
      }
      if (oldVersion < 2) {
        // Add index for completed status
        const transaction = db.transaction(['todos'], 'readwrite');
        const todosStore = transaction.objectStore('todos');
        if (!todosStore.indexNames.contains('completed')) {
          todosStore.createIndex('completed', 'completed', { unique: false });
        }
      }
    }
  }
);

const addTodo = async (title: string) => {
  const todo: TodoItem = {
    id: crypto.randomUUID(),
    title,
    completed: false,
    createdAt: new Date()
  };
  await setItem(todo.id, todo);
};

const loadAllTodos = async () => {
  const keys = await getAllKeys();
  const todos = await Promise.all(
    keys.map(key => getItem(key))
  );
  return todos.filter(Boolean) as TodoItem[];
};

File Storage

Storing and retrieving files using IndexedDB

const { setItem, getItem } = useIndexedDB<File>('fileStorage', 'files');

const handleFileUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
  const file = event.target.files?.[0];
  if (file) {
    try {
      await setItem(file.name, file);
      console.log('File stored successfully!');
    } catch (err) {
      console.error('Failed to store file:', err);
    }
  }
};

const downloadFile = async (fileName: string) => {
  try {
    const file = await getItem(fileName);
    if (file) {
      const url = URL.createObjectURL(file);
      const a = document.createElement('a');
      a.href = url;
      a.download = fileName;
      a.click();
      URL.revokeObjectURL(url);
    }
  } catch (err) {
    console.error('Failed to download file:', err);
  }
};

return (
  <div>
    <input type="file" onChange={handleFileUpload} />
    <button onClick={() => downloadFile('example.txt')}>
      Download File
    </button>
  </div>
);

Dependencies

react

Notes

•IndexedDB is asynchronous and more powerful than localStorage for large amounts of data
•Supports storing complex objects, files, and blobs without serialization
•Automatically handles database initialization and schema upgrades
•Provides transaction-based operations for data consistency
•Works offline and follows same-origin policy
•Browser storage quotas apply - see MDN documentation for details
•Not available in all environments (e.g., some private browsing modes)
•All operations are Promise-based for better async handling

Implementation

"use client";

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

interface UseIndexedDBOptions {
  version?: number;
  onUpgradeNeeded?: (
    db: IDBDatabase,
    oldVersion: number,
    newVersion: number
  ) => void;
}

interface UseIndexedDBReturn<T> {
  data: T | null;
  error: string | null;
  loading: boolean;
  setItem: (key: string, value: T) => Promise<void>;
  getItem: (key: string) => Promise<T | null>;
  removeItem: (key: string) => Promise<void>;
  clear: () => Promise<void>;
  getAllKeys: () => Promise<string[]>;
}

export function useIndexedDB<T = any>(
  databaseName: string,
  storeName: string,
  options: UseIndexedDBOptions = {}
): UseIndexedDBReturn<T> {
  const [data, setData] = useState<T | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState<boolean>(false);
  const [db, setDb] = useState<IDBDatabase | null>(null);

  const { version = 1, onUpgradeNeeded } = options;

  // Initialize IndexedDB connection
  useEffect(() => {
    if (typeof window === "undefined") return;

    const initDB = async () => {
      try {
        setLoading(true);
        setError(null);

        const request = indexedDB.open(databaseName, version);

        request.onerror = () => {
          setError(`Failed to open database: ${request.error?.message}`);
          setLoading(false);
        };

        request.onsuccess = () => {
          setDb(request.result);
          setLoading(false);
        };

        request.onupgradeneeded = (event) => {
          const database = request.result;
          const oldVersion = event.oldVersion;
          const newVersion = event.newVersion || version;

          // Create object store if it doesn't exist
          if (!database.objectStoreNames.contains(storeName)) {
            database.createObjectStore(storeName);
          }

          // Call custom upgrade handler if provided
          if (onUpgradeNeeded) {
            onUpgradeNeeded(database, oldVersion, newVersion);
          }
        };
      } catch (err) {
        setError(`IndexedDB initialization error: ${err}`);
        setLoading(false);
      }
    };

    initDB();

    return () => {
      if (db) {
        db.close();
      }
    };
  }, [databaseName, storeName, version, onUpgradeNeeded]);

  // Set item in IndexedDB
  const setItem = useCallback(
    async (key: string, value: T): Promise<void> => {
      if (!db) {
        throw new Error("Database not initialized");
      }

      return new Promise((resolve, reject) => {
        const transaction = db.transaction([storeName], "readwrite");
        const store = transaction.objectStore(storeName);
        const request = store.put(value, key);

        request.onsuccess = () => {
          setData(value);
          resolve();
        };

        request.onerror = () => {
          const errorMsg = `Failed to set item: ${request.error?.message}`;
          setError(errorMsg);
          reject(new Error(errorMsg));
        };
      });
    },
    [db, storeName]
  );

  // Get item from IndexedDB
  const getItem = useCallback(
    async (key: string): Promise<T | null> => {
      if (!db) {
        throw new Error("Database not initialized");
      }

      return new Promise((resolve, reject) => {
        const transaction = db.transaction([storeName], "readonly");
        const store = transaction.objectStore(storeName);
        const request = store.get(key);

        request.onsuccess = () => {
          const result = request.result || null;
          setData(result);
          resolve(result);
        };

        request.onerror = () => {
          const errorMsg = `Failed to get item: ${request.error?.message}`;
          setError(errorMsg);
          reject(new Error(errorMsg));
        };
      });
    },
    [db, storeName]
  );

  // Remove item from IndexedDB
  const removeItem = useCallback(
    async (key: string): Promise<void> => {
      if (!db) {
        throw new Error("Database not initialized");
      }

      return new Promise((resolve, reject) => {
        const transaction = db.transaction([storeName], "readwrite");
        const store = transaction.objectStore(storeName);
        const request = store.delete(key);

        request.onsuccess = () => {
          setData(null);
          resolve();
        };

        request.onerror = () => {
          const errorMsg = `Failed to remove item: ${request.error?.message}`;
          setError(errorMsg);
          reject(new Error(errorMsg));
        };
      });
    },
    [db, storeName]
  );

  // Clear all items from the store
  const clear = useCallback(async (): Promise<void> => {
    if (!db) {
      throw new Error("Database not initialized");
    }

    return new Promise((resolve, reject) => {
      const transaction = db.transaction([storeName], "readwrite");
      const store = transaction.objectStore(storeName);
      const request = store.clear();

      request.onsuccess = () => {
        setData(null);
        resolve();
      };

      request.onerror = () => {
        const errorMsg = `Failed to clear store: ${request.error?.message}`;
        setError(errorMsg);
        reject(new Error(errorMsg));
      };
    });
  }, [db, storeName]);

  // Get all keys from the store
  const getAllKeys = useCallback(async (): Promise<string[]> => {
    if (!db) {
      throw new Error("Database not initialized");
    }

    return new Promise((resolve, reject) => {
      const transaction = db.transaction([storeName], "readonly");
      const store = transaction.objectStore(storeName);
      const request = store.getAllKeys();

      request.onsuccess = () => {
        resolve(request.result as string[]);
      };

      request.onerror = () => {
        const errorMsg = `Failed to get keys: ${request.error?.message}`;
        setError(errorMsg);
        reject(new Error(errorMsg));
      };
    });
  }, [db, storeName]);

  return {
    data,
    error,
    loading,
    setItem,
    getItem,
    removeItem,
    clear,
    getAllKeys,
  };
}

useCounter

CLI Docs All Hooks

useLocalStorage