HTML IndexedDB

Introduction

IndexedDB is a low-level API for storing large amounts of structured data in the browser—including files and blobs. Unlike localStorage and sessionStorage, which only hold strings, IndexedDB gives you object stores, indexes, transactions, and key-based access. That makes it the right choice for offline apps, cached API responses, and complex client-side data.

This page is your central hub: learn core concepts here, browse 4 dedicated CRUD tutorials below, and practice with live Try It examples. If you are coming from Web SQL, think of object stores as tables—but you work with JavaScript objects, not SQL strings.

What You’ll Learn

What Is IndexedDB?

IndexedDB is a transactional database system built into modern browsers. You store and retrieve JavaScript objects using keys—similar to a NoSQL document store. The API is entirely asynchronous: requests return immediately and fire callbacks or resolve promises later, so the main thread never blocks while disk I/O runs.

IndexedDB is the W3C-standard replacement for deprecated Web SQL. It is supported in Chrome, Firefox, Safari, and Edge, making it the default choice for client-side structured storage in 2026.

Key Features of IndexedDB

• Structured data storage — save plain objects, arrays, Date values, ArrayBuffer, Blob, and File instances.
• Indexing — create indexes on object properties for fast lookups without scanning every record.
• Transactions — group multiple operations into one atomic unit; all succeed or all roll back.
• Asynchronous API — event-driven requests (onsuccess, onerror) keep the UI responsive. Modern code can also use the promise-based indexedDB.databases() and wrapper libraries.
• Origin-scoped persistence — data survives page reloads until the user clears site data or storage quota is exceeded.
• Large capacity — browsers typically allow hundreds of megabytes per origin (varies by device and free disk space).

Basic Concepts

Before writing code, learn these terms—they appear in every IndexedDB program:

• Database — the top-level container (opened with indexedDB.open(name, version)). One origin can have many databases.
• Object store — a collection of records, like a table without fixed columns. Each record is a JavaScript object.
• Key / keyPath — the unique identifier for a record. Set keyPath: 'id' on the store, or use autoIncrement: true to generate numeric keys.
• Index — a secondary lookup path on a property (e.g. index on email for fast searches by email).
• Transaction — a scope for reading or writing one or more object stores. Modes: readonly or readwrite.
• Cursor — an iterator that walks records one at a time with cursor.continue().
• Version upgrade — the only time you can create, rename, or delete object stores—inside onupgradeneeded when the version number increases.

Creating and Opening a Database

Call indexedDB.open('myDatabase', version). The second argument is a version number (integer). On first open, version 1 creates the database. To add a new object store later, bump the version and handle onupgradeneeded:

let db;

const request = indexedDB.open('myDatabase', 1);

request.onupgradeneeded = function (event) {
  db = event.target.result;
  const objectStore = db.createObjectStore('myObjectStore', { keyPath: 'id' });
  objectStore.createIndex('nameIndex', 'name', { unique: false });
};

request.onsuccess = function (event) {
  db = event.target.result;
  console.log('Database ready');
};

request.onerror = function (event) {
  console.error('Database error:', event.target.error.message);
};

onupgradeneeded runs before onsuccess when the version changes. Create all stores and indexes there—never inside a normal transaction on first visit.

Working with Object Stores

Object stores hold your records. To add data, start a readwrite transaction, get the store, and call add() or put():

function addItem(item) {
  const transaction = db.transaction(['myObjectStore'], 'readwrite');
  const objectStore = transaction.objectStore('myObjectStore');
  const request = objectStore.add(item);

  request.onsuccess = function () {
    console.log('Item added successfully.');
  };

  request.onerror = function (event) {
    console.error('Add item error:', event.target.error.message);
  };
}

addItem({ id: 1, name: 'Notebook', qty: 3 });

See the dedicated INSERT tutorial for add() vs put(), auto-increment keys, and storing blobs.

Transactions and Cursors

Transactions ensure operations complete as a unit. To read every record, open a readonly transaction and use openCursor():

function getAllItems() {
  const transaction = db.transaction(['myObjectStore'], 'readonly');
  const objectStore = transaction.objectStore('myObjectStore');
  const request = objectStore.openCursor();

  request.onsuccess = function (event) {
    const cursor = event.target.result;
    if (cursor) {
      console.log('Item:', cursor.value);
      cursor.continue();
    } else {
      console.log('No more items.');
    }
  };

  request.onerror = function (event) {
    console.error('Cursor error:', event.target.error.message);
  };
}

For a single key, store.get(key) is simpler. For many keys at once, getAll() returns an array. The Retrieve tutorial covers indexes and filtered cursors in depth.

Handling Errors

Every IndexedDB request can fail—quota exceeded, duplicate key on add(), or invalid transaction. Attach onerror handlers and read event.target.error.message (not the legacy errorCode property):

request.onerror = function (event) {
  console.error('Error:', event.target.error.message);
};

transaction.onabort = function () {
  console.warn('Transaction aborted — no changes were saved.');
};

transaction.oncomplete = function () {
  console.log('Transaction committed successfully.');
};

Also listen for db.onversionchange when another tab upgrades the database—close your connection so the upgrade can finish.

Examples Gallery

Five progressive examples from opening a database to a complete mini app. Use Try It Yourself to run live demos in your browser.

if (!window.indexedDB) {
  console.warn('IndexedDB not supported');
} else {
  const req = indexedDB.open('myDatabase', 1);
  req.onupgradeneeded = function (e) {
    e.target.result.createObjectStore('contacts', { keyPath: 'id', autoIncrement: true });
  };
  req.onsuccess = function () { console.log('Ready'); };
}

Ready

const tx = db.transaction(['contacts'], 'readwrite');
const store = tx.objectStore('contacts');
store.add({ name: 'Jane Doe', email: 'jane@example.com' });

tx.oncomplete = function () {
  console.log('Contact saved');
};

Contact saved

const tx = db.transaction(['contacts'], 'readonly');
const req = tx.objectStore('contacts').openCursor();

req.onsuccess = function (e) {
  const cursor = e.target.result;
  if (cursor) {
    console.log(cursor.key, cursor.value.name);
    cursor.continue();
  }
};

1 Jane Doe
2 John Smith

request.onupgradeneeded = function (event) {
  const store = event.target.result
    .createObjectStore('contacts', { keyPath: 'id', autoIncrement: true });
  store.createIndex('byEmail', 'email', { unique: true });
};

// Later: lookup by email
const index = tx.objectStore('contacts').index('byEmail');
index.get('jane@example.com').onsuccess = function (e) {
  console.log(e.target.result);
};

{ id: 1, name: 'Jane Doe', email: 'jane@example.com' }

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>IndexedDB Example</title>
</head>
<body>
  <h1>IndexedDB Example</h1>
  <button id="add">Add Item</button>
  <button id="get">Get All Items</button>
  <script>
    let db;
    const request = indexedDB.open('myDatabase', 1);
    request.onupgradeneeded = function (e) {
      e.target.result.createObjectStore('myObjectStore', { keyPath: 'id', autoIncrement: true });
    };
    request.onsuccess = function (e) { db = e.target.result; };

    document.getElementById('add').addEventListener('click', function () {
      const tx = db.transaction(['myObjectStore'], 'readwrite');
      tx.objectStore('myObjectStore').add({ name: 'Sample Item ' + Date.now() });
    });

    document.getElementById('get').addEventListener('click', function () {
      const tx = db.transaction(['myObjectStore'], 'readonly');
      const req = tx.objectStore('myObjectStore').openCursor();
      req.onsuccess = function (e) {
        const cursor = e.target.result;
        if (cursor) {
          console.log('Item:', cursor.value);
          cursor.continue();
        }
      };
    });
  </script>
</body>
</html>

Item: { id: 1, name: 'Sample Item 1720000000123' }

Use Cases

IndexedDB shines whenever the browser must own structured data without a live network:

• Offline-first PWAs — cache API JSON, sync when back online.
• Draft autosave — store form state locally so refresh does not lose work.
• Media and file caching — persist Blob thumbnails or downloaded PDFs.
• Game progress — save levels, inventory, and settings as objects.
• Analytics buffers — queue events locally, flush in batches to the server.
• Replacing Web SQL — migrate legacy SQL apps to object stores and indexes.

Best Practices

📝 Notes

• IndexedDB is not a SQL database—there is no SELECT * FROM syntax.
• Data is isolated per origin (scheme + host + port). Other sites cannot read your database.
• Users clearing browser data wipes IndexedDB for that site.
• Private browsing may use in-memory storage that disappears when the session ends.
• Continue to DELETE, INSERT, Retrieve, and UPDATE for operation-specific guides.
• Coming from Web SQL? IndexedDB is the modern, cross-browser replacement.