Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
initDB
✓ import { initDB } from 'react-indexed-db-hook';
✗ const { initDB } = require('react-indexed-db-hook');
Required to initialize the IndexedDB configuration globally before any hooks or context are used. Typically called once at the application's entry point.
useIndexedDB
✓ import { useIndexedDB } from 'react-indexed-db-hook';
✗ import useIndexedDB from 'react-indexed-db-hook';
The primary hook for interacting with a specific object store. It's a named export, not a default export. Pass the store name as an argument.
IndexedDB (Context Provider)
✓ import { IndexedDB } from 'react-indexed-db-hook';
✗ import IndexedDB from 'react-indexed-db-hook';
Although available, the maintainer does not plan on supporting the context API in the future. Prefer `initDB` and `useIndexedDB`.
AccessDB (Context Consumer)
✓ import { AccessDB } from 'react-indexed-db-hook';
Consumer for the `IndexedDB` context. Similar to `IndexedDB` provider, its use is discouraged due to lack of future support.
This quickstart demonstrates how to initialize the IndexedDB, use the `useIndexedDB` hook to perform CRUD operations (add, get, update, delete) on an 'items' object store, and display the items in a React component.
import React, { useEffect, useState } from 'react';
import { initDB, useIndexedDB } from 'react-indexed-db-hook';
// 1. Define your DB configuration
export const DBConfig = {
name: 'MyTestDB',
version: 1,
objectStoresMeta: [
{
store: 'items',
storeConfig: { keyPath: 'id', autoIncrement: true },
storeSchema: [
{ name: 'name', keypath: 'name', options: { unique: false } },
{ name: 'value', keypath: 'value', options: { unique: false } }
]
}
]
};
// 2. Initialize the DB once at the application entry point
initDB(DBConfig);
interface Item {
id?: number;
name: string;
value: string;
}
const ItemManager: React.FC = () => {
const { add, getAll, getByID, update, deleteRecord } = useIndexedDB<Item>('items');
const [items, setItems] = useState<Item[]>([]);
const [newItemName, setNewItemName] = useState('');
const [newItemValue, setNewItemValue] = useState('');
const [selectedItemId, setSelectedItemId] = useState<number | null>(null);
const [editItemName, setEditItemName] = useState('');
const [editItemValue, setEditItemNameValue] = useState('');
const refreshItems = async () => {
const allItems = await getAll();
setItems(allItems);
};
useEffect(() => {
refreshItems();
}, []);
const handleAddItem = async () => {
await add({ name: newItemName, value: newItemValue });
setNewItemName('');
setNewItemValue('');
refreshItems();
};
const handleEditSelect = async (id: number) => {
const item = await getByID(id);
if (item) {
setSelectedItemId(id);
setEditItemName(item.name);
setEditItemNameValue(item.value);
}
};
const handleUpdateItem = async () => {
if (selectedItemId) {
await update({ id: selectedItemId, name: editItemName, value: editItemValue });
setSelectedItemId(null);
setEditItemName('');
setEditItemNameValue('');
refreshItems();
}
};
const handleDeleteItem = async (id: number) => {
await deleteRecord(id);
refreshItems();
};
return (
<div>
<h1>Items</h1>
<div>
<input
type="text"
placeholder="Name"
value={newItemName}
onChange={(e) => setNewItemName(e.target.value)}
/>
<input
type="text"
placeholder="Value"
value={newItemValue}
onChange={(e) => setNewItemValue(e.target.value)}
/>
<button onClick={handleAddItem}>Add Item</button>
</div>
{selectedItemId && (
<div>
<h3>Edit Item (ID: {selectedItemId})</h3>
<input
type="text"
value={editItemName}
onChange={(e) => setEditItemName(e.target.value)}
/>
<input
type="text"
value={editItemValue}
onChange={(e) => setEditItemNameValue(e.target.value)}
/>
<button onClick={handleUpdateItem}>Update Item</button>
<button onClick={() => setSelectedItemId(null)}>Cancel</button>
</div>
)}
<ul>
{items.map((item) => (
<li key={item.id}>
{item.name}: {item.value}
<button onClick={() => handleEditSelect(item.id!)}>Edit</button>
<button onClick={() => handleDeleteItem(item.id!)}>Delete</button>
</li>
))}
</ul>
</div>
);
};
export default ItemManager;
Errors
Common errors & fixes
Uncaught (in promise) DOMException: The database is not running any transactions.
This usually indicates that `initDB` was not called or failed before attempting to use database operations via `useIndexedDB`.
fixEnsure `initDB(DBConfig)` is called successfully at your application's entry point, before any components requiring IndexedDB access are rendered.
Property 'add' does not exist on type '{ ... }'. Did you mean 'addRecord'?
Incorrect method name or type inference issue. The library provides `add`, `getAll`, `getByID`, `update`, `deleteRecord`.
fixDouble-check the method names from the `useIndexedDB` hook. The correct method for adding a record is `add` (not `addRecord` or `insert`). Ensure your TypeScript generic `useIndexedDB<T>` correctly reflects the type of objects in your store.
Uncaught (in promise) DOMException: An object store with the specified name was not found or has been deleted.
The object store name provided to `useIndexedDB('storeName')` does not match any store defined in `DBConfig.objectStoresMeta`.
fixVerify that the string argument passed to `useIndexedDB` exactly matches the `store` property in one of your `objectStoresMeta` configurations in `DBConfig`.
Audit
Dependencies
reactrequiredPeer dependency required for all React components and hooks.