React IndexedDB Hook

1.0.14 · maintenance · verified Wed Apr 22

The `react-indexed-db-hook` package provides a React hook-based abstraction over the browser's native IndexedDB API. It simplifies common database operations like initializing the database, creating object stores, and performing CRUD operations (add, get, update, delete) within React components. The current stable version is 1.0.14, last published over three years ago, indicating a slower release cadence, likely in maintenance mode rather than active development with new features. It aims to make the powerful, asynchronous, and transactional IndexedDB API more accessible to React developers, offering a more robust client-side storage solution than `localStorage` for larger, structured datasets, and enabling offline-first application capabilities.

Common errors

```
Failed to open IndexedDB: A mutation operation was attempted on a database that did not allow mutations.
```
cause Attempting to change database schema (e.g., add or modify an object store or index) without incrementing the database version in `initDB`.

fix Increment the `version` property in your `dbConfig` object passed to `initDB` whenever you make schema changes to your `objectStoresMeta`.
```
Uncaught (in promise) DOMException: Failed to execute 'transaction' on 'IDBDatabase': The database is not running a versionchange transaction.
```
cause This often occurs when trying to perform write operations (add, put, delete) on IndexedDB outside of an active write transaction context, or when a transaction has already completed.

fix Ensure that all write operations are performed within the scope of a transaction explicitly created for that purpose. The `useIndexedDB` hook is designed to manage these transactions, so this error might indicate incorrect usage of the hook's methods or an attempt to use IndexedDB directly without proper transaction handling.
```
ReferenceError: window is not defined
```
cause Attempting to run IndexedDB-related code, which is a browser API, in a Node.js environment (e.g., during Server-Side Rendering with Next.js or other SSR frameworks).

fix Wrap your IndexedDB-dependent code in client-side checks (`if (typeof window !== 'undefined')`) or dynamically import components that use `react-indexed-db-hook` to ensure they only render in the browser.

Warnings

gotcha IndexedDB is a browser-only API. Using `react-indexed-db-hook` directly in Server-Side Rendering (SSR) environments (like Next.js or Astro) will result in `window is not defined` errors. Ensure IndexedDB-related code runs only on the client-side, typically by dynamically importing components or checking `typeof window !== 'undefined'`.
Fix: Guard IndexedDB usage with client-side checks or dynamic imports for SSR applications. Example: `if (typeof window !== 'undefined') { // IndexedDB code }`.
breaking Changing `keyPath` or adding new indexes to an existing object store requires incrementing the database version in `initDB`. Failure to do so will result in `DOMException: A mutation operation was attempted on a database that did not allow mutations` or `VersionError`.
Fix: When modifying your `dbConfig` (e.g., changing `objectStoresMeta`), increment the `version` number in `initDB`. Handle schema migrations in the `onupgradeneeded` event if more complex logic is required (though this library abstracts some of that).
gotcha IndexedDB operations can be 'blocked' if the database is open in other browser tabs or instances when an `onupgradeneeded` event is triggered. This can prevent schema changes or even database deletion.
Fix: Inform users to close other tabs if they encounter 'blocked' errors during database upgrades or deletions. For critical updates, consider using `IDBFactory.deleteDatabase()` with `onblocked` handling, or implement a version migration strategy that gracefully handles conflicts.
gotcha The `react-indexed-db-hook` package has not been updated in over three years (last published 2022-11-27). While functional, it may not receive new features, performance optimizations, or prompt bug fixes compared to more actively maintained IndexedDB wrappers or state management libraries.
Fix: Evaluate your project's needs for active maintenance and support. For long-term projects or those requiring advanced features, consider alternatives like `Dexie.js` or `RxDB` which provide more robust and actively developed abstractions over IndexedDB.

Install

npm install react-indexed-db-hook npm
yarn add react-indexed-db-hook yarn
pnpm add react-indexed-db-hook pnpm

Imports

initDB
wrong:
```
import initDB from 'react-indexed-db-hook';
```
correct:
```
import { initDB } from 'react-indexed-db-hook';
```
Used once at application startup to configure IndexedDB database name, version, and object stores (schemas). It is a named import.
useIndexedDB
wrong:
```
import useIndexedDB from 'react-indexed-db-hook';
```
correct:
```
import { useIndexedDB } from 'react-indexed-db-hook';
```
The primary React hook for interacting with a specific IndexedDB object store. It provides methods for CRUD operations.
DBConfig
```
import type { DBConfig } from 'react-indexed-db-hook';
```
Type definition for the database configuration object passed to `initDB`.

Quickstart

Demonstrates initializing the IndexedDB database, adding a new user to an object store, and retrieving all users using the `useIndexedDB` hook. This covers basic setup and CRUD operations.

import React, { useEffect, useState } from 'react';
import { initDB, useIndexedDB } from 'react-indexed-db-hook';

interface User {
  id?: number;
  name: string;
  email: string;
}

// 1. Define your database configuration
const dbConfig = {
  name: 'MyDatabase',
  version: 1,
  objectStoresMeta: [
    {
      store: 'users',
      storeConfig: { keyPath: 'id', autoIncrement: true },
      storeSchema: [
        { name: 'name', keypath: 'name', options: { unique: false } },
        { name: 'email', keypath: 'email', options: { unique: true } },
      ],
    },
  ],
};

// 2. Initialize the database (typically once in your app's entry point)
initDB(dbConfig);

function UserForm() {
  const { add, getAll } = useIndexedDB<User>('users');
  const [name, setName] = useState('');
  const [email, setEmail] = useState('');
  const [users, setUsers] = useState<User[]>([]);

  useEffect(() => {
    // Fetch all users on component mount
    getAll().then((data) => {
      setUsers(data);
    });
  }, [getAll]);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!name || !email) return;

    try {
      const userId = await add({ name, email });
      alert(`User added with ID: ${userId}`);
      setName('');
      setEmail('');
      // Re-fetch users to update the list
      getAll().then((data) => setUsers(data));
    } catch (error) {
      console.error('Error adding user:', error);
      alert('Failed to add user. Email might already exist.');
    }
  };

  return (
    <div>
      <h1>Add New User</h1>
      <form onSubmit={handleSubmit}>
        <input
          type="text"
          placeholder="Name"
          value={name}
          onChange={(e) => setName(e.target.value)}
        />
        <input
          type="email"
          placeholder="Email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
        <button type="submit">Add User</button>
      </form>

      <h2>Users List</h2>
      {users.length === 0 ? (
        <p>No users yet.</p>
      ) : (
        <ul>
          {users.map((user) => (
            <li key={user.id}>
              {user.name} ({user.email})
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

export default UserForm;

view raw JSON →