Storing Complex Objects & Blobs in IndexedDB0%

Storing Complex Objects & Blobs in IndexedDB

Beginner12 min read•Updated: Jul 11, 2026

Storing Complex Objects & Blobs in IndexedDB

One of the greatest capabilities of IndexedDB is its native support for the Structured Clone Algorithm. Unlike localStorage (which requires manual JSON.stringify that strips binary data and types), IndexedDB natively stores complex JavaScript objects—including Blob, File, ArrayBuffer, Date, Map, Set, and cyclic objects.

1. Supported Types vs. JSON Limitations

Data Type	`localStorage` (via JSON)	IndexedDB (Structured Clone)
Binary Blobs & Files	Drops or requires huge base64 strings	Native binary storage (Zero overhead)
TypedArrays & ArrayBuffers	Loses typed structure	Supported natively
Date Objects	Converted to plain ISO string	Preserved as true `Date` instances
RegExp Objects	Lost / converted to empty object `{}`	Preserved
Circular Object References	Throws `TypeError: Converting circular structure`	Supported natively

2. Storing & Retrieving Binary Images and PDF Blobs

In an offline PWA or multimedia app, you can download files via fetch(), store the raw binary Blob directly in IndexedDB, and render it offline without network access:

JavaScript

1// Function to download and persist an image file offline
2async function cacheImageOffline(db, imageUrl, imageId) {
// Step 1: Download raw binary blob
const response = await fetch(imageUrl);
const blob = await response.blob();
6 
// Step 2: Store directly into IndexedDB
const tx = db.transaction(['mediaStore'], 'readwrite');
const store = tx.objectStore('mediaStore');
10 
store.put({
  id: imageId,
  contentType: blob.type,
  fileData: blob, // Storing raw binary Blob directly!
  savedAt: new Date()
});
17 
return new Promise((resolve) => {
  tx.oncomplete = () => {
    console.log(`Image "${imageId}" stored offline in IndexedDB.`);
    resolve();
  };
});
24}

3. Rendering Stored Blobs in the DOM

To display a stored Blob without uploading or converting to base64, use URL.createObjectURL():

JavaScript

1async function displayOfflineImage(db, imageId, imgElement) {
const tx = db.transaction(['mediaStore'], 'readonly');
const store = tx.objectStore('mediaStore');
const request = store.get(imageId);
5 
request.onsuccess = () => {
  const record = request.result;
  if (record && record.fileData instanceof Blob) {
    // Generate a temporary local object URL
    const objectUrl = URL.createObjectURL(record.fileData);
    imgElement.src = objectUrl;
12 
    // Clean up object URL when image loads to prevent memory leaks
    imgElement.onload = () => URL.revokeObjectURL(objectUrl);
  }
};
17}

Output

1Network / File System ──► Blob ──► IndexedDB (Binary on disk)
                                       │
                                       ▼ URL.createObjectURL()
                                 blob:https://... ──► <img src="...">

4. Storing Multi-Tier Relational Graphs

Because IndexedDB uses the Structured Clone Algorithm, complex hierarchical objects with circular relationships can be stored safely:

JavaScript

1const nodeA = { name: 'Node Alpha' };
2const nodeB = { name: 'Node Beta', partner: nodeA };
3nodeA.partner = nodeB; // Circular reference!
4 
5// Storing in IndexedDB:
6const tx = db.transaction(['graphStore'], 'readwrite');
7tx.objectStore('graphStore').put({ id: 'graph_1', root: nodeA });
8// Succeeds without error! JSON.stringify would have thrown an exception!

Interactive Quiz• Knowledge Check

Practice Quiz

Question 1

What algorithm enables IndexedDB to natively store Blobs, Dates, and cyclic references without JSON.stringify()?

Question 2

What Web API function creates a temporary DOMString URL (e.g. blob:https://...) from a stored Blob for rendering in an <img> tag?

Question 3

Why is storing large binary files as Blobs in IndexedDB superior to storing Base64 strings in localStorage?

Question 4

What should you call after an image has finished loading a blob: URL to prevent memory leaks in the browser?

Question 5

What happens if you attempt to store an object with circular references into IndexedDB?

Next Lesson

Cache API & Service Worker Storage

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
IndexedDB Architecture & Transactions	Cache API & Service Worker Storage

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

Previous Next

PreviousPrevNext