DEV Community: Sohail Khan

Why Fabric.js `loadFromJSON` Can Leave Your Editor Half-Loaded

Sohail Khan — Thu, 01 Oct 2026 07:34:52 +0000

A saved Fabric.js document can reopen with missing content when an image URL fails and the loading path allows failed objects to be omitted. fabricjs-document-engine checks external images before loading content into the canvas and rejects unresolved images with MISSING_ASSETS, including the affected URLs and object IDs.

The practical goal is simple: keep the current drawing visible, explain why the next document could not open, and let the user fix the missing asset.

This guide uses React and the public API in fabricjs-document-engine 1.0.2, checked on October 1, 2026. The native Fabric.js behavior discussed below is version-specific, with Fabric.js 7.4.0 as the concrete example. The engine supports Fabric.js 6 and 7. The quick-start guide covers installation and engine setup.

Does a failed image always leave Fabric.js partially loaded?

No. A failed image is not a universal explanation for every blank or incomplete canvas, and Fabric.js versions do not all handle failed object creation identically.

Fabric.js 7.4.0 creates objects before loadFromJSON clears and replaces the canvas. Its object-enlivening code collects failed object results and calls the reviver with the error. If the reviver supplies no replacement and throws no error, a failed object can be omitted while successful objects are installed.

That can produce a document which looks partly restored: text and shapes appear, but an image is gone. By contrast, Fabric.js 6 uses a different object-enlivening failure path; do not assume a Fabric 7 example describes every Fabric 6 failure.

The relevant primary sources are Fabric.js's loadFromJSON API, canvas implementation, and object-enlivening implementation. These two source links are pinned to the commit recorded for Fabric.js 7.4.0. Compare that implementation with the version installed in your app.

The document engine adds two relevant checks:

Check external assets. Fail with a missing-image report before invoking the canvas loader.
Refuse dropped objects. Use a strict reviver when Fabric.js creates document objects.

The package's Fabric adapter source shows the strict reviver. Its asset preparation source shows where missing-image checks run.

Why can a valid canvas JSON file still fail to reopen?

Valid JSON describes the document. It does not guarantee that every dependency still exists.

An image object may contain a src pointing to a deleted file, an expired signed URL, an unavailable host, or a blob: URL from a previous browser session. The JSON can parse successfully while the browser cannot load that image.

Symptom	What to check
Shapes load but a picture disappears	Failed image request; omitted object in the loading path
A document works until refresh	A tab-only `blob:` image was saved without durable upload
An image displays but PNG export fails	Canvas tainting and image CORS settings
Text uses the wrong face or layout	Font availability before text creation
An older document replaces a newer selection	Overlapping requests and loads
Objects appear only after clicking the canvas	Rendering after the asynchronous load

A missing image and a tainted canvas need different fixes. A missing image cannot be loaded. A tainted canvas may display an image while the browser blocks reading the canvas pixels for export.

The package's images and fonts guide separates asset loading, font fallback, and CORS/export problems. The troubleshooting guide covers related editor symptoms.

Why does clearing the canvas before loading make failures worse?

This code discards the current drawing before the next document has opened:

// Fragile app code: the old drawing is removed before the load succeeds.
canvas.clear();
await canvas.loadFromJSON(savedJson);
canvas.requestRenderAll();

If loading fails, the app has already removed the old objects. Catching the error afterward does not reconstruct those objects.

Do not clear the canvas before asking the engine to open a document. Let the engine validate and prepare the incoming content first:

await engine.loadDocument(savedDocument);

If a storage adapter is configured, open a saved record by its document ID:

await engine.load("design-42");

loadDocument accepts a document value. load(id) first asks the storage adapter for that value. Both use the engine's document-loading path.

See the save and load guide and document engine API for the method signatures.

What happens before the engine mutates the canvas content?

The engine prepares the incoming document before passing it to Fabric.js. With image checks enabled, the loading path does the following:

Check the input. Apply content limits, migrate supported formats, and validate the document.
Check object types. Refuse classes that have not been registered.
Resolve asset URLs. Run an optional assets.resolveUrl handler.
Check dependencies. Check external images and font availability.
Try replacements. Run an optional assets.replaceMissingImage handler for missing images.
Reject missing images. Throw MISSING_ASSETS if unresolved images remain.
Load the content. Invoke Fabric.js with the engine's strict reviver.

For the MISSING_ASSETS failure in step 6, the canvas content has not been replaced. The error carries a list shaped like this:

error.missingAssets;
// [
//   { url: "/uploads/deleted-logo.png", objectIds: ["logo-image"] }
// ]

This guarantee is specific to failures detected before canvas loading. It is not a claim that every possible exception, custom-class side effect, or later Fabric.js failure can be rolled back. Embedded data: images are not fetched by the external-image preflight; malformed embedded data can fail during object creation instead.

Keep image checks enabled when you want this preflight behavior. Setting assets.checkImages: false skips the external-image check and removes the early missing-asset report.

The exact order is visible in the engine loading source and the asset preparation source. The images and fonts documentation explains the public behavior.

How do you prove that a failed image leaves the current drawing intact?

Use a controlled missing-image document and compare the canvas objects before and after the rejected load. Serve the app locally and ensure the test image address returns a real failure; a development server that substitutes a valid image would defeat the test.

import { Canvas, Textbox } from "fabric";
import {
  createDocumentEngine,
  isDocumentEngineError,
  type FabricDocument,
} from "fabricjs-document-engine";

export async function demonstrateMissingImage(element: HTMLCanvasElement) {
  const canvas = new Canvas(element, { width: 800, height: 500 });
  // No storage is configured in this isolated loading demonstration.
  const engine = createDocumentEngine({ canvas });
  canvas.add(new Textbox("Keep the current drawing", { left: 40, top: 40 }));

  const currentObjects = canvas.getObjects().slice();
  const timestamp = new Date().toISOString();
  const incoming: FabricDocument = {
    schemaVersion: 1,
    id: "broken-design",
    createdAt: timestamp,
    updatedAt: timestamp,
    revision: 1,
    canvas: { width: 800, height: 500 },
    objects: [{
      type: "Image",
      id: "logo-image",
      src: "/uploads/intentionally-missing-logo.png",
      width: 120,
      height: 120,
    }],
    metadata: {},
  };

  try {
    await engine.loadDocument(incoming);
    throw new Error("The test URL unexpectedly loaded.");
  } catch (error) {
    if (!isDocumentEngineError(error) || error.code !== "MISSING_ASSETS") {
      throw error;
    }
    const after = canvas.getObjects();
    if (after.length !== currentObjects.length ||
        after.some((object, index) => object !== currentObjects[index])) {
      throw new Error("The current drawing was changed.");
    }
    return { code: error.code, missingAssets: error.missingAssets };
  } finally {
    engine.destroy();
    await canvas.dispose();
  }
}

Use a dedicated canvas element for this helper. It creates and disposes its own canvas; do not pass the DOM element of an editor that already owns a Fabric.js instance.

The expected result is MISSING_ASSETS, the failed URL, and logo-image. The object-reference check confirms that the existing drawing survived the rejected load. The package repository contains a related browser test for missing images before canvas mutation.

This helper was run in Chromium against package 1.0.2 and Fabric.js 7.4.0. It returned MISSING_ASSETS with the expected URL and object ID, and the original canvas object references remained unchanged. A separate native Fabric.js load with one rectangle and one unavailable image restored the rectangle and omitted the image. The complete TypeScript examples in this article also passed type checking.

The example intentionally has no storage adapter so it tests image preflight directly. A persistent editor should also protect unsaved changes, as the React example below does.

How do you show the engine error in a React editor?

Catch the rejected operation and branch on the stable error code. Show missingAssets to the user instead of silently logging a generic failure.

Install the packages:

npm install fabric fabricjs-document-engine

This component is a complete local demonstration. It uses the built-in memory adapter, so saved records last only while that adapter remains in memory. Add text, save it, and try opening the broken document.

"use client";

import { Canvas, Textbox } from "fabric";
import {
  isDocumentEngineError,
  type DocumentEngineError,
  type FabricDocument,
} from "fabricjs-document-engine";
import { createMemoryStorage } from "fabricjs-document-engine/storage";
import {
  useDocumentEngine,
  useDocumentState,
} from "fabricjs-document-engine/react";
import { useEffect, useRef, useState } from "react";

const storage = createMemoryStorage();
const timestamp = new Date().toISOString();
const brokenDocument: FabricDocument = {
  schemaVersion: 1,
  id: "broken-design",
  createdAt: timestamp,
  updatedAt: timestamp,
  revision: 1,
  canvas: { width: 800, height: 500 },
  objects: [{
    type: "Image",
    id: "logo-image",
    src: "/uploads/intentionally-missing-logo.png",
    width: 120,
    height: 120,
  }],
  metadata: {},
};

export function SafeLoadEditor() {
  const elementRef = useRef<HTMLCanvasElement>(null);
  const [canvas, setCanvas] = useState<Canvas | null>(null);
  const [problem, setProblem] = useState<DocumentEngineError | null>(null);
  const [message, setMessage] = useState("");
  const [busy, setBusy] = useState(false);

  useEffect(() => {
    if (!elementRef.current) return;
    const created = new Canvas(elementRef.current, { width: 800, height: 500 });
    setCanvas(created);
    return () => { void created.dispose().catch(() => undefined); };
  }, []);

  const engine = useDocumentEngine(canvas, {
    storage,
    document: { id: "working-design" },
  });
  const state = useDocumentState(engine);

  async function run(action: () => Promise<unknown>, success: string) {
    setBusy(true);
    setProblem(null);
    setMessage("");
    try {
      await action();
      setMessage(success);
    } catch (error) {
      if (isDocumentEngineError(error)) {
        if (error.code === "LOAD_ABORTED") return;
        setProblem(error);
      } else {
        setMessage(error instanceof Error ? error.message : "Opening failed.");
      }
    } finally {
      setBusy(false);
    }
  }

  const disabled = !engine || busy || Boolean(state?.isSaving || state?.isLoading);

  return (
    <section>
      <button disabled={disabled} onClick={() => canvas?.add(
        new Textbox("Keep the current drawing", { left: 40, top: 40 })
      )}>Add text</button>
      <button disabled={disabled} onClick={() => {
        if (engine) void run(() => engine.save(), "Current drawing saved.");
      }}>Save current drawing</button>
      <button disabled={disabled} onClick={() => {
        if (engine) void run(
          () => engine.loadDocument(brokenDocument),
          "Document opened."
        );
      }}>Try opening the broken document</button>

      {problem?.code === "MISSING_ASSETS" ? (
        <div role="alert">
          <p>The document could not open. These images are unavailable:</p>
          <ul>
            {problem.missingAssets.map((asset) => (
              <li key={asset.url}>
                <code>{asset.url}</code>
                {" — Objects: "}{asset.objectIds.join(", ")}
              </li>
            ))}
          </ul>
          <p>Your current drawing is still visible.</p>
        </div>
      ) : problem?.code === "UNSAVED_CHANGES" ? (
        <p role="alert">Save the current drawing before opening another document.</p>
      ) : problem ? (
        <p role="alert">{problem.code}: {problem.message}</p>
      ) : null}

      <p role="status">{message}</p>
      <p aria-live="polite">{state?.saveStatus ?? "Preparing editor"}</p>
      <canvas ref={elementRef} aria-label="Drawing preserved after a failed load" />
    </section>
  );
}

Clicking Try opening the broken document before saving an edit should show UNSAVED_CHANGES. After saving, the same operation reaches image preflight and should show MISSING_ASSETS. The app never passes discardUnsavedChanges: true automatically.

For an API-backed editor, replace the memory adapter with your HTTP adapter and call engine.load(documentId) inside the same handler. The companion guide, Save Fabric.js Canvas JSON to an API and Open It by Document ID, includes the adapter and app-owned endpoint.

The React guide, React hooks reference, and error code reference document the hooks and error fields used here.

Should you catch errors or subscribe to `load:error`?

Use the operation's catch when the result belongs to a particular button, route, or document selection. Use load:error when a shared panel or logging system needs to observe engine loading failures.

import { useDocumentEvent } from "fabricjs-document-engine/react";

// Inside a React component that already has an engine.
useDocumentEvent(engine, "load:error", ({ error }) => {
  if (error.code === "LOAD_ABORTED") return;
  console.error("Document loading failed", error.code, error);
});

The event observes an error; it does not consume the promise rejection. Still handle the promise returned by engine.load() or engine.loadDocument(). If both paths show notifications, one failure can produce duplicate messages.

An unsaved-change guard can reject before the loading sequence starts. Catching the requested operation also covers that case. useDocumentState(engine) exposes loadError for failures tracked by the state store, but a persistent guard message should not depend only on that field.

The event payload is { error }, not the error directly. See the events API for the exact contract.

How do you repair a missing image without removing the object?

Use assets.replaceMissingImage when your app has a known replacement. The hook receives the missing URL and the object IDs that refer to it.

const engine = createDocumentEngine({
  canvas,
  storage,
  assets: {
    replaceMissingImage(image) {
      if (image.url === "/uploads/deleted-logo.png") {
        return "/assets/replacement-logo.png";
      }
      return null;
    },
  },
});

This is an engine-options fragment; canvas and storage are the instances already owned by your app, and createDocumentEngine is imported from the package.

The engine checks the replacement URL too. If the replacement is also unavailable, the load still fails. If the replacement works, loading can continue and the engine reports an IMAGE_REPLACED warning.

A replacement policy changes document content. Make that policy clear to the user. For client artwork, returning null and asking for a replacement may be preferable to inserting a generic placeholder.

Save deliberately after a repaired load if the new address should be retained. A successful load begins a saved session; do not assume the replacement alone has marked the document dirty or written a new record to your backend.

See the asset options guide and createDocumentEngine API. engine.replaceImage(oldUrl, newUrl) repairs images already present in the current canvas; it does not modify an incoming document that preflight rejected.

What if the image URL expires instead of disappearing?

Resolve the stored asset address into a currently accessible URL with assets.resolveUrl. Your app can use that handler to request a fresh signed URL from its backend before the engine checks and loads the image.

const assets = {
  async resolveUrl(url: string) {
    if (!url.startsWith("asset://")) return url;
    const assetId = url.slice("asset://".length);
    const response = await fetch(
      `/api/assets/${encodeURIComponent(assetId)}/url`
    );
    if (!response.ok) throw new Error("The asset address could not be resolved.");
    const result = (await response.json()) as { url: string };
    return result.url;
  },
};

The asset-resolution endpoint is app-owned backend code. The package does not implement asset permissions or signed-URL generation.

Also plan the return path when saving. The engine rewrites the incoming image address to the resolved URL; saving that content can persist the signed URL. Keep durable asset identity in app-managed data and normalize addresses in your storage layer if your API requires stable identifiers.

For tab-only blob: images, configure assets.upload while saving so reopening does not depend on the previous tab. Both hooks are described in the images and fonts guide.

Can you fix an image CORS failure from React alone?

The image host must permit the cross-origin request when the image is loaded with CORS enabled. Setting crossOrigin: "anonymous" in React or Fabric.js does not create permission on the remote server.

Check both the image request and response headers. For a canvas that displays correctly but cannot export, inspect whether the image was loaded in a way that tainted the canvas.

The engine's IMAGE_CROSS_ORIGIN warning helps identify risky image references. Export preflight can reject a raster export with EXPORT_BLOCKED; that is a different error from loading a document with MISSING_ASSETS.

Read the CORS guidance and export guide. The engine reports the problem; your app and image host control how the asset is served.

What should the editor do with each loading error?

Use error codes to decide what action to offer. Do not match error-message wording.

Engine code	Useful editor response
`MISSING_ASSETS`	List missing image URLs and affected object IDs; offer repair or retry
`MISSING_FONTS`	Load the required fonts or explain why the document cannot open
`UNKNOWN_OBJECT_TYPE`	Register the missing custom class before retrying
`INVALID_DOCUMENT`	Show document validation details; request a valid saved record
`UNSAVED_CHANGES`	Offer save, cancel, or an explicit discard decision
`DOCUMENT_NOT_FOUND`	Explain that the requested stored document is unavailable
`LOAD_ABORTED`	Usually keep quiet when a newer document selection superseded the request
`LOAD_FAILED`	Inspect the storage or Fabric.js failure and the underlying `cause`

Missing fonts normally produce FONT_UNAVAILABLE warnings and fallback text. Set assets.requireFonts: true when the document must not open with fallback fonts; unavailable fonts then produce MISSING_FONTS.

The package's error code reference and custom object guide describe these cases.

Will awaiting `loadFromJSON` solve every loading problem?

Awaiting the load is necessary for code that depends on loaded objects. It does not make deleted images available or register a missing custom class.

For a direct Fabric.js load, a basic successful path is:

await canvas.loadFromJSON(savedJson);
canvas.requestRenderAll();

That fixes the timing of rendering after the promise settles. With Fabric.js versions that permit failed objects to be omitted, a fulfilled promise alone does not prove every expected object was restored.

When using the document engine, wait for its load method. The engine requests rendering after its successful load.

How do you keep an older load from replacing a newer document?

Use engine.load(id) for the complete storage-and-loading operation. The engine claims the load before reading storage, so a slower response for an older selection cannot replace a newer completed load. A superseded request rejects with LOAD_ABORTED.

If your app separately fetches JSON and then calls loadDocument, your app must also prevent older fetch responses from being submitted after newer ones. The engine cannot know that a later loadDocument call came from an earlier UI selection.

The loading API documents the entry points, and the engine source shows the storage-response guard. Fabric.js itself also warns about overlapping loads in its loadFromJSON reference.

Start with one deliberately missing image. Confirm that the old drawing stays visible, the error contains the image URL and object IDs, and the React UI explains the failure. Then test expired URLs, missing fonts, and overlapping document selections against your own storage. The npm package, quick start, and GitHub repository provide the source and further examples.

Save Fabric.js Canvas JSON to an API and Open It by Document ID

Sohail Khan — Thu, 01 Oct 2026 05:25:57 +0000

To save a Fabric.js canvas to a database, send its editable JSON through an API and retrieve that JSON when the user opens the document. With fabricjs-document-engine on npm, a storage adapter connects engine.save() and engine.load(documentId) to your own HTTP endpoints.

The package manages the document workflow around your existing Fabric.js canvas. Your app owns the API, authentication, database, and file storage. You can keep the toolbar and React components you already have.

This guide builds a React editor, a typed HTTP adapter, and an Express/PostgreSQL endpoint. The examples follow the public API in package 1.0.2, checked on October 1, 2026. The package supports Fabric.js 6 and 7. Start with the official quick-start guide if you have not created an engine before.

What should you save to reopen an editable Fabric.js canvas?

Save the document JSON. A PNG is useful for a thumbnail or download, but a PNG does not preserve independently editable text, shapes, groups, and object properties.

Fabric.js supplies serialization through canvas.toJSON() and canvas.toObject(). The document engine adds the information needed to identify, reopen, and save a document consistently:

Saved field	Purpose
`id`	Finds the document through your API
`schemaVersion`	Identifies the engine's document format
`revision`	Detects a save based on an older stored revision
`canvas`	Records width, height, and background
`objects`	Records serialized objects in stacking order, with stable IDs
`assets`	Lists external images and font variants used by objects
`metadata`	Holds app data such as the document title

Store the complete document body. Keeping only objects would remove the document ID, revision, and canvas dimensions that the rest of this example uses.

The document format reference describes the exact fields. The save and load guide explains how the engine serializes an existing canvas.

What is the storage adapter contract?

A basic DocumentStorage adapter has two required methods: one reads a document and one saves it. The engine does not prescribe a database, URL structure, or server framework.

import type { FabricDocument } from "fabricjs-document-engine";

// The public contract, shown here for reference.
interface DocumentStorage {
  loadDocument(id: string): Promise<unknown>;
  saveDocument(
    document: FabricDocument,
    context: {
      expectedRevision: number | null;
      signal: AbortSignal;
    }
  ): Promise<void | { revision?: number }>;
}

loadDocument returns unknown because storage is an external boundary. The engine checks the returned document before loading its content.

expectedRevision is the revision this editor last loaded or saved. A new document starts at revision 0. The outgoing document normally carries the next revision. If your server assigns the revision, return the accepted value as { revision }.

A value of null means the caller requested an overwrite. Pass the provided signal to the save request so the engine can abort the client request when the session changes. Request cancellation does not undo a write that the server has already committed.

These behaviors come from the storage API reference and the custom backend guide. Optional version-storage methods are outside this article's two-method adapter.

How do you connect the document engine to an HTTP API?

Install Fabric.js and the document engine in your React app:

npm install fabric fabricjs-document-engine

Create api-storage.ts. This adapter uses same-origin endpoints and your app's existing session cookie.

import {
  DocumentEngineError,
  type DocumentStorage,
} from "fabricjs-document-engine";

export const apiStorage: DocumentStorage = {
  async loadDocument(id) {
    const response = await fetch(
      `/api/documents/${encodeURIComponent(id)}`,
      { cache: "no-store" }
    );

    if (response.status === 404) {
      throw new DocumentEngineError(
        "DOCUMENT_NOT_FOUND",
        "This document was not found."
      );
    }
    if (!response.ok) {
      throw new Error(`Opening the document failed (${response.status}).`);
    }
    return response.json();
  },

  async saveDocument(document, { expectedRevision, signal }) {
    const response = await fetch(
      `/api/documents/${encodeURIComponent(document.id)}`,
      {
        method: "PUT",
        signal,
        headers: {
          "Content-Type": "application/json",
          "X-Expected-Revision":
            expectedRevision === null ? "*" : String(expectedRevision),
        },
        body: JSON.stringify(document),
      }
    );

    if (response.status === 409 || response.status === 412) {
      throw new DocumentEngineError(
        "SAVE_CONFLICT",
        "Another tab or device saved this document first."
      );
    }
    if ([400, 401, 403, 404, 413, 422].includes(response.status)) {
      throw Object.assign(
        new Error(`The server refused this save (${response.status}).`),
        { retryable: false }
      );
    }
    if (!response.ok) {
      throw new Error(`Saving the document failed (${response.status}).`);
    }

    const result = (await response.json()) as { revision?: unknown };
    if (!Number.isSafeInteger(result.revision) || Number(result.revision) < 1) {
      throw Object.assign(new Error("The API returned an invalid revision."), {
        retryable: false,
      });
    }
    return { revision: Number(result.revision) };
  },
};

X-Expected-Revision is an app-defined header. In this example, 0 means create a document and * means explicitly overwrite an existing one. These are conventions shared by this adapter and the endpoint below; the package does not require this header.

The official REST storage example uses If-Match. This article uses a custom header to keep its numeric revision protocol separate from standard HTTP entity-tag semantics.

Throwing SAVE_CONFLICT tells the engine to stop retrying that save. Setting retryable: false also stops retries for errors that require a change to the request or permissions. Other save failures can follow the engine's retry policy.

How do you save and open a document in React?

First, create the Fabric.js canvas after React mounts the canvas element. Put this helper in use-fabric-canvas.ts:

import { Canvas } from "fabric";
import { useEffect, useRef, useState } from "react";

export function useFabricCanvas() {
  const elementRef = useRef<HTMLCanvasElement>(null);
  const [canvas, setCanvas] = useState<Canvas | null>(null);

  useEffect(() => {
    if (!elementRef.current) return;
    const created = new Canvas(elementRef.current, {
      width: 800,
      height: 500,
    });
    setCanvas(created);
    return () => {
      void created.dispose().catch(() => undefined);
    };
  }, []);

  return { elementRef, canvas };
}

Then create document-editor.tsx:

"use client";

import { Rect } from "fabric";
import { isDocumentEngineError } from "fabricjs-document-engine";
import {
  useDocumentEngine,
  useDocumentState,
} from "fabricjs-document-engine/react";
import { useState } from "react";
import { apiStorage } from "./api-storage";
import { useFabricCanvas } from "./use-fabric-canvas";

export function DocumentEditor() {
  const { elementRef, canvas } = useFabricCanvas();
  const engine = useDocumentEngine(canvas, {
    storage: apiStorage,
    document: { id: "design-42", metadata: { title: "First design" } },
  });
  const state = useDocumentState(engine);
  const [documentId, setDocumentId] = useState("design-42");
  const [busy, setBusy] = useState(false);
  const [message, setMessage] = useState("");

  async function run(action: () => Promise<unknown>, success: string) {
    setBusy(true);
    setMessage("");
    try {
      await action();
      setMessage(success);
    } catch (error) {
      if (isDocumentEngineError(error) && error.code === "LOAD_ABORTED") return;
      if (isDocumentEngineError(error) && error.code === "UNSAVED_CHANGES") {
        setMessage("Save your current changes before opening another document.");
      } else if (isDocumentEngineError(error) && error.code === "SAVE_CONFLICT") {
        setMessage("A newer revision exists. Review the conflict before continuing.");
      } else {
        setMessage(error instanceof Error ? error.message : "The request failed.");
      }
    } finally {
      setBusy(false);
    }
  }

  const disabled = !engine || busy || Boolean(state?.isSaving || state?.isLoading);

  return (
    <section>
      <label>
        Document ID
        <input
          value={documentId}
          onChange={(event) => setDocumentId(event.target.value)}
        />
      </label>
      <button
        disabled={disabled || !documentId.trim()}
        onClick={() => {
          if (engine) void run(
            () => engine.load(documentId.trim()),
            "Document opened."
          );
        }}
      >Open</button>
      <button
        disabled={disabled}
        onClick={() => canvas?.add(new Rect({
          left: 80, top: 60, width: 160, height: 100, fill: "#6366f1",
        }))}
      >Add rectangle</button>
      <button
        disabled={disabled}
        onClick={() => {
          if (engine) void run(() => engine.save(), "Save confirmed by the API.");
        }}
      >Save</button>
      <p aria-live="polite">
        Current document: {state?.documentId ?? "Preparing editor"}
        {state ? ` · Revision ${state.revision} · ${state.saveStatus}` : ""}
      </p>
      <p role="status">{message}</p>
      <canvas ref={elementRef} aria-label="Editable design canvas" />
    </section>
  );
}

Add a rectangle and click Save. The adapter sends the full document to PUT /api/documents/design-42. Refresh the page and click Open to retrieve it through GET /api/documents/design-42.

The text field chooses the document to open. Changing the text field does not rename the current document. A save always uses the engine's current document ID, shown below the buttons.

The example uses manual saves to make the request flow visible. To add autosave, pass autosave: true when creating the engine and continue displaying state.saveStatus and state.saveError. Options are read when the hook creates the engine; changing an options object later does not reconfigure that engine.

See the React guide, React hooks API, and autosave guide. In Next.js, mount Fabric.js through the client-only setup in the Next.js guide.

What does the app-owned HTTP endpoint look like?

The following backend code belongs to your application. It is an illustrative Express 5 and PostgreSQL implementation, not an endpoint supplied by fabricjs-document-engine.

Create a table through your app's database migration:

CREATE TABLE documents (
  owner_id text NOT NULL,
  id text NOT NULL,
  body jsonb NOT NULL,
  revision integer NOT NULL CHECK (revision >= 1),
  PRIMARY KEY (owner_id, id)
);

Use your existing authentication middleware as requireUser. That middleware must verify the session, reject unauthenticated requests, and set req.auth.userId. Neither the middleware nor DATABASE_URL comes from the package.

// server.ts — app-owned backend, using Express 5.
import express from "express";
import { Pool } from "pg";
import { validateDocument, type FabricDocument } from "fabricjs-document-engine";
import { requireUser } from "./app-auth"; // Your verified-session middleware.

declare global {
  namespace Express {
    interface Request { auth: { userId: string } }
  }
}

const app = express();
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

app.use(requireUser);
app.use(express.json({ limit: "2mb" })); // An app-chosen request limit.

app.get("/api/documents/:id", async (req, res) => {
  const result = await pool.query(
    "SELECT body FROM documents WHERE owner_id = $1 AND id = $2",
    [req.auth.userId, req.params.id]
  );
  if (result.rowCount === 0) {
    res.status(404).json({ error: "DOCUMENT_NOT_FOUND" });
    return;
  }
  res.set("Cache-Control", "no-store").json(result.rows[0].body);
});

app.put("/api/documents/:id", async (req, res) => {
  const header = req.get("X-Expected-Revision");
  if (!header || (header !== "*" && !/^(0|[1-9]\d*)$/.test(header))) {
    res.status(400).json({ error: "INVALID_EXPECTED_REVISION" });
    return;
  }
  const expected = header === "*" ? null : Number(header);
  if (expected !== null && (!Number.isSafeInteger(expected) || expected > 2147483646)) {
    res.status(400).json({ error: "INVALID_EXPECTED_REVISION" });
    return;
  }

  const value: unknown = req.body;
  const issues = validateDocument(value);
  if (issues.length > 0) {
    res.status(422).json({ error: "INVALID_DOCUMENT", issues });
    return;
  }
  const document = value as FabricDocument;
  if (document.id !== req.params.id) {
    res.status(422).json({ error: "DOCUMENT_ID_MISMATCH" });
    return;
  }

  const params = [req.auth.userId, document.id, JSON.stringify(document)];
  const result = expected === 0
    ? await pool.query(
        `INSERT INTO documents (owner_id, id, body, revision)
         VALUES ($1, $2, jsonb_set($3::jsonb, '{revision}', '1'::jsonb), 1)
         ON CONFLICT (owner_id, id) DO NOTHING
         RETURNING revision`,
        params
      )
    : await pool.query(
        `UPDATE documents
         SET body = jsonb_set($3::jsonb, '{revision}', to_jsonb(revision + 1)),
             revision = revision + 1
         WHERE owner_id = $1 AND id = $2
           AND ($4::integer IS NULL OR revision = $4::integer)
         RETURNING revision`,
        [...params, expected]
      );

  if (result.rowCount === 0) {
    res.status(409).json({ error: "SAVE_CONFLICT" });
    return;
  }
  res.status(expected === 0 ? 201 : 200).json({
    revision: result.rows[0].revision,
  });
});

app.listen(3001);

Run the API behind the same origin as the React app, or configure a development proxy for /api. Apply your existing session and CSRF policy to these routes. A document ID locates a row; ownership comes from the verified session, never from metadata.owner supplied by the browser.

The endpoint assigns revisions and writes that value into both the JSON body and the revision column. This keeps the next GET consistent with the previous save response. Its overwrite branch updates an existing row; it does not recreate a deleted document. A missing row or revision mismatch returns 409.

The 2mb limit is an example application limit, not a package limit. Adjust it for your documents. validateDocument checks the document shape; enforce any additional object-count, URL, asset, or business rules in your backend too.

The SQL follows the package's atomic revision-check guidance. See PostgreSQL's UPDATE and RETURNING documentation for the database behavior. Express 5 forwards rejected async route handlers to error handling; integrate your app's normal handler using the Express error-handling guide.

How does a revision check prevent lost updates?

Suppose two tabs open revision 4 of the same document. Both tabs edit it. Without a server-side check, the second save can overwrite the first save without warning.

Request	Expected revision	Stored revision before request	Result
Tab A saves	`4`	`4`	Accepted; server stores revision `5`
Tab B saves	`4`	`5`	Rejected with HTTP `409`
Tab B adapter handles response	—	`5`	Throws `SAVE_CONFLICT`

These numbers illustrate the protocol; they are not a performance measurement.

Check the revision and write the document in the same database operation. A separate SELECT followed by an unconditional UPDATE leaves room for another request to save between them.

The engine also serializes saves within one editor session. That does not replace a database revision check across tabs, devices, or API clients.

For conflict UI, offer to review the stored document or deliberately overwrite it. engine.save({ overwrite: true }) passes expectedRevision: null; use that only after the user chooses to overwrite. Loading a newer document can also replace unsaved work, so make that choice explicit before passing discardUnsavedChanges: true.

Read the save conflicts guide for the full decision flow.

Are image files stored inside the canvas JSON?

A normal image object stores an address for its image. Saving that address does not upload the file. In particular, a blob: URL refers to data in the current browser environment and is unsuitable for reopening on another device.

Configure assets.upload to turn tab-only images into durable URLs while the engine prepares a save:

// Add this assets option when creating the engine.
const assets = {
  async upload({ blob }: { blob: Blob }) {
    const body = new FormData();
    body.append("file", blob);
    const response = await fetch("/api/uploads", { method: "POST", body });
    if (!response.ok) throw new Error("The image could not be uploaded.");
    const result = (await response.json()) as { url: string };
    return result.url;
  },
};

/api/uploads is another app-owned endpoint. It must save the file and return an address that your readers can access. The package does not create an S3 bucket, configure a CDN, or supply the upload route.

Avoid treating an expiring signed URL as a permanent asset identity. The images and fonts guide explains assets.upload and assets.resolveUrl, including how to resolve stored asset addresses when opening a document.

If a stored image cannot be opened, see the companion article, Why Fabric.js loadFromJSON Can Leave Your Editor Half-Loaded.

What should you check before shipping this save flow?

Verify the complete round trip, including failures:

Reopen the document. Save, refresh, and open the same ID.
Compare the content. Check object IDs, canvas dimensions, and stacking order.
Create a conflict. Open two tabs; confirm the older revision cannot overwrite the newer save.
Reject invalid input. Send a mismatched document ID and malformed document body.
Check ownership. Confirm another account cannot read or write the document.
Interrupt a request. Confirm the UI does not claim a failed save succeeded.
Reopen uploaded images. Test from a fresh browser session.

The adapter verification guide helps check storage behavior. The production checklist covers the wider editor lifecycle.

For this article, the complete TypeScript examples passed type checking against package 1.0.2 and Fabric.js 7.4.0. A Chromium check with the built-in memory adapter confirmed that saved object IDs and canvas dimensions survived reopening, the first save produced revision 1, and an older editor's save produced SAVE_CONFLICT. The HTTP/PostgreSQL endpoint is an illustrative implementation; connect and test it with your app's actual authentication and database.

Retries need one extra decision in your API: a write can succeed even if its response is lost. Retrying with the old expected revision can then produce a conflict. This sample preserves the stored document rather than guessing. If your app needs transparent retry acknowledgments, implement request idempotency on the server.

Can you use MongoDB, MySQL, or a different backend?

Yes. The adapter sends plain JSON and returns a revision. Replace the PostgreSQL endpoint with your own backend while keeping the two storage methods and an atomic revision condition.

For MongoDB, the equivalent idea is a conditional update filtered by document ID, owner, and expected revision. The exact database code belongs to your app. The package does not ship a MongoDB model or a MySQL table.

Can you open JSON saved by an older Fabric.js editor?

The engine can recognize plain Fabric.js JSON through load, loadDocument, and importFabricJson. A document loaded by engine.load(id) retains that requested ID, and its next save uses the engine's current document format.

Check the migration guide before moving existing records. Back up the stored JSON and test your custom classes and assets. The API example above validates incoming saves in the engine's document format.

Does calling `toDocument()` mean the canvas has been saved?

No. engine.toDocument() produces a document object. engine.save() uses the configured storage adapter and updates the engine's save state after storage accepts the write.

Use toDocument() when you need a snapshot. Use save() for the managed persistence flow shown here.

Start with a manual save and an open-by-ID action. Once the round trip and conflicts work with your real storage, add autosave and image uploads. The npm package, quick start, and GitHub repository contain the implementation and related examples.

Fabric.js Editor Problems: Save, Load, Undo, Autosave, and Recovery

Sohail Khan — Wed, 30 Sep 2026 06:47:52 +0000

Fabric.js makes it easy to put shapes, text, and images on a canvas. Building an editor around that canvas takes more work. You need to know which object is which after a reload, how to undo a drag, what to do when an image disappears, and whether a slow save can overwrite a newer one.

These are the problems fabricjs-document-engine is built to handle. It connects to a Fabric.js canvas you already own. You keep your own toolbar, storage service, and user interface. The package adds the document workflow around them.

This guide starts with the problems people actually describe, then shows what the package does and where your application still has work to do. The examples use the published 1.0.2 API with Fabric.js 7. The package also supports Fabric.js 6. For a complete first project, see the save and load tutorial.

The short answer

What a developer searches for	What is happening	Where the package helps
“Fabric.js undo redo not working”	History must be built around object changes and asynchronous loads.	Action-level history, `undo()`, `redo()`, transactions.
“Fabric.js custom properties lost after JSON load”	Extra fields need explicit serialization and class registration.	Register the class and its saved properties once.
“Fabric.js object reference lost after undo”	Reloading creates new object instances.	Stable IDs and `getObjectById()`.
“Fabric.js loadFromJSON missing image”	Saved image URLs may expire or fail to load.	Check assets before replacing the current canvas; report missing URLs.
“Fabric.js autosave overwrites newer changes”	Requests and edits can overlap.	One in-flight save, a follow-up save, and revision checks.
“Fabric.js canvas lost after refresh”	Unsaved edits never reached durable storage.	Optional local recovery checkpoints and a restore flow.
“Fabric.js tainted canvas export”	Browser CORS rules block raster output.	Export preflight reports the problem; your image host must allow CORS.

These are search phrases, not claims that every report is a Fabric.js core bug. Many are integration problems that appear when an application grows from a drawing canvas into an editor. The Fabric.js API already includes serialization and image export. The package coordinates them into a document lifecycle.

Start with a canvas and a document

Install the package with a supported Fabric version:

npm install fabric@^7 fabricjs-document-engine@1.0.2

Here is a small setup using the built-in browser storage adapter. The HTML page needs <canvas id="editor"></canvas>.

import { Canvas, Rect } from "fabric";
import { createDocumentEngine } from "fabricjs-document-engine";
import { createLocalStorage } from "fabricjs-document-engine/storage";

const canvas = new Canvas("editor", {
  width: 800,
  height: 500,
  backgroundColor: "#f8fafc",
});

const engine = createDocumentEngine({
  canvas,
  document: { id: "poster-42" },
  storage: createLocalStorage({ prefix: "my-editor:" }),
  autosave: { delay: 1000, maxWait: 10000 },
});

canvas.add(new Rect({
  left: 80,
  top: 70,
  width: 180,
  height: 120,
  fill: "#4f46e5",
}));

await engine.save();

The document option gives this design a known ID. createLocalStorage is useful for a prototype on one browser. For a product with accounts or multiple devices, provide a backend storage adapter. The engine does not host your files or create your API.

You can also use engine.toDocument() and engine.loadDocument(json) without any adapter. Those calls serialize and open a document you store yourself. engine.save(), engine.load(id), autosave, and versions need an adapter. See the creation options and storage guide.

1. “Fabric.js undo redo not working”

Fabric.js has no built-in document history. A developer in Fabric.js issue #10011 tried to add history to a Fabric 6 editor. The thread includes two familiar problems: older callback-style loadFromJSON code no longer matched the promise API, and objects were hard to identify after loading a prior snapshot. It is an example of the integration work a history system requires, not evidence that Fabric.js drawing is broken.

The engine records object additions and removals, pointer moves and transforms, and completed text edits. One user action becomes one history step. Your toolbar can ask whether a step is available:

In this snippet, undoButton and redoButton are your toolbar's button elements.

undoButton.disabled = !engine.canUndo();
redoButton.disabled = !engine.canRedo();

undoButton.addEventListener("click", () => void engine.undo());
redoButton.addEventListener("click", () => void engine.redo());

A detail that matters: calling object.set() in your own code does not necessarily fire a Fabric event. If your toolbar changes several properties, group them yourself:

Here card is the Fabric object your editor is changing.

engine.transaction("Move and recolor card", () => {
  card.set({ left: 200, top: 120, fill: "#f97316" });
  card.setCoords();
  canvas.requestRenderAll();
});

That whole command becomes one labelled undo step. You can also make changes first and call engine.commit("Recolor card"). Read the undo and redo guide for the automatic events, keyboard shortcuts, and history limits.

2. “Fabric.js object reference lost after undo or reload”

An undo operation or JSON load often creates new JavaScript object instances. A variable that pointed to the old rectangle may no longer point to the rectangle now on the canvas. Fabric.js issue #6799 also shows how group-relative transforms make object state harder to reason about.

The engine assigns a stable ID to each object, including children inside groups. Save the ID in your application state. After a load or undo, find the current instance:

const id = card.id;

await engine.undo();

const currentCard = engine.getObjectById(id);
if (currentCard) {
  currentCard.set("fill", "#2563eb");
  canvas.requestRenderAll();
  engine.commit("Recolor card");
}

This solves identity across document operations. It does not calculate canvas-relative coordinates for a grouped object or fix every transform issue in #6799. For those, use Fabric.js transformation APIs. The engine's document format explains object IDs and order.

3. “Fabric.js custom properties lost after JSON load”

An editor often adds fields such as label, databaseId, or lockedBy. Fabric.js supports custom serialization, but you must configure it. The request in issue #10887 describes the repeated setup developers face when storing application metadata on objects. Its native custom properties guide is also worth reading.

For a custom class, register its type and the properties that must survive a document round trip:

import { Rect } from "fabric";
import { createDocumentEngine } from "fabricjs-document-engine";

class Sticker extends Rect {
  static type = "Sticker";
  declare label: string;
}

const engine = createDocumentEngine({
  canvas,
  customObjects: [
    { fabricClass: Sticker, properties: ["label"] },
  ],
});

Set label on a Sticker, save, and load it again. You do not have to remember to list that property on every toJSON() call. Register the class before you load a document that uses it. Otherwise, the load fails with UNKNOWN_OBJECT_TYPE instead of quietly changing it to another shape. See custom objects.

This feature is for Fabric classes and object fields. Put whole-document information such as a title or customer ID in document metadata, using engine.updateMetadata({ title: "Summer poster" }).

4. “Fabric.js loadFromJSON failed” or “the old canvas disappeared”

Loading is more than parsing JSON. A saved design can contain an unknown custom class, a malformed value, an expired image URL, or a newer schema. There may also be two loads in progress because the user quickly opened design A and then design B.

The engine validates and checks the incoming document before replacing the current canvas. An unknown type fails with UNKNOWN_OBJECT_TYPE. A missing image fails with MISSING_ASSETS. If B starts after A, A is cancelled with LOAD_ABORTED, so its late response cannot replace B. The save and load guide documents these rules.

try {
  await engine.load("poster-42");
  showMessage("Poster opened");
} catch (error) {
  if (error.code === "LOAD_ABORTED") return;
  if (error.code === "UNSAVED_CHANGES") {
    showMessage("Save or discard your current edits first");
    return;
  }
  showMessage(`Could not open the poster: ${error.message}`);
}

When storage is configured, the engine also refuses to replace unsaved work unless the user has chosen to discard it. Do not pass discardUnsavedChanges: true automatically. A failed load should leave the design people were editing on screen. The error code reference lists the cases your UI can handle.

5. “Fabric.js autosave overwrites newer changes”

Fabric.js does not decide when your app sends a document to a server. A common editor mistake is to fire a request after every change. Request A might start first but finish after request B, leaving older content in storage.

With a storage adapter, the engine keeps one save in flight. If edits happen during that save, it schedules one follow-up save with the latest content. engine.isDirty() and engine.getSaveState() let you show what is saved. Temporary failures can be retried. The exact timing and retry options are in the autosave guide.

engine.on("save:status", ({ status, isDirty, revision }) => {
  statusElement.textContent = `${status} · revision ${revision}`;
  saveButton.disabled = !isDirty;
});

One tab is only half the problem. If another tab or device has saved the same document, a correct adapter compares revisions and reports SAVE_CONFLICT. The app can offer to reload, save a copy, or deliberately overwrite. Do not choose overwrite silently. The built-in adapters check revisions; your own backend must enforce the same rule at the database write. See save conflicts and the custom backend example.

Put the same save rules on your backend

For an account-based editor, write a storage adapter around your API. This TypeScript example assumes your server returns a document on GET, and { revision: number } on a successful PUT:

import type { DocumentStorage } from "fabricjs-document-engine";

const storage: DocumentStorage = {
  async loadDocument(id) {
    const response = await fetch(`/api/documents/${encodeURIComponent(id)}`);
    if (!response.ok) throw new Error(`Load failed: ${response.status}`);
    return response.json();
  },

  async saveDocument(document, { expectedRevision, signal }) {
    const response = await fetch(
      `/api/documents/${encodeURIComponent(document.id)}`,
      {
        method: "PUT",
        headers: {
          "Content-Type": "application/json",
          "If-Match": String(expectedRevision ?? "*"),
        },
        body: JSON.stringify(document),
        signal,
      },
    );

    if (response.status === 409) {
      throw Object.assign(new Error("Saved in another tab"), {
        code: "SAVE_CONFLICT",
      });
    }
    if (!response.ok) throw new Error(`Save failed: ${response.status}`);
    return response.json(); // { revision: number }
  },
};

Your server must check expectedRevision against the stored revision as part of the write, then return the new revision. A client-side comparison alone cannot stop two devices from racing. Add authorization for each document ID and decide how your UI presents a conflict. The package's backend guide and adapter verification guide cover the full contract.

6. “Fabric.js image missing after load” and “my font changed”

The JSON can be valid while the resources it refers to are gone. An image may point to an expired signed URL. A browser-only blob: URL will disappear after refresh. A web font might not be ready when Fabric measures text.

The engine records an asset manifest with the image and font variants a document uses. It checks them before loading. MISSING_ASSETS includes the missing image URLs and object IDs; unavailable fonts can produce warnings or fail the load if you require them. You can resolve URLs, offer replacement images, load fonts, and upload temporary images through asset options.

const report = await engine.checkAssets();
console.log(report.missingImages, report.unavailableFonts);

// If a stored image URL has moved:
await engine.replaceImage("/old-logo.png", "/new-logo.png");

The package can tell you what is missing and use a replacement you provide. It cannot revive a deleted image on your server. If designs need to open on other devices, upload browser-only images to durable storage and return a portable URL. For web fonts, make the font available and load it before you rely on its measured text layout.

7. “Fabric.js canvas lost after refresh or crash”

Autosave helps, but a tab can close while edits are still unsaved or a request is in flight. Optional recovery keeps a separate local checkpoint. It uses IndexedDB while the person edits and can offer a copy after refresh or interruption.

import { createIndexedDbRecovery } from "fabricjs-document-engine/recovery";

const engine = createDocumentEngine({
  canvas,
  storage,
  recovery: { store: createIndexedDbRecovery(), interval: 2000 },
});

const recoverable = await engine.getRecoverableDocuments();
if (recoverable.length > 0 && window.confirm("Restore unsaved work?")) {
  await engine.restoreRecovery(recoverable[0].documentId);
}

The confirmation demonstrates the choice. In a real editor, show a useful preview and let the user restore or discard a copy before replacing what is currently on screen. Recovery is local to the browser; it is not a server backup or multi-device sync. Private browsing and storage clearing can remove it. Read the recovery guide for checkpoint timing and temporary images.

8. “Fabric.js tainted canvas cannot be exported”

A Fabric.js user reported that exporting after loadFromJSON hit a tainted-canvas error in issue #5429. This is a browser security rule when a remote image is drawn without the required cross-origin permission. The package cannot bypass that rule.

It can check before export and give you a useful problem list:

const check = await engine.preflightExport({ format: "png" });
if (!check.ok) {
  showProblems(check.problems);
} else {
  const result = await engine.export({
    format: "png",
    area: "content",
    scale: 2,
    background: "transparent",
  });
  // Download or upload result.blob.
}

The export API also supports JPEG, WebP, SVG, and editable JSON. You can choose the canvas, content, selection, or an explicit rectangle as the output area. A blocked raster export reports EXPORT_BLOCKED; successful export does not change the editable canvas or its undo state. See export.

To actually fix a cross-origin image, load it with appropriate crossOrigin settings and configure its server to send the correct Access-Control-Allow-Origin header. See the package troubleshooting guide. Switching packages will not remove the browser's CORS requirement.

9. “How do I keep versions of a Fabric.js design?”

Undo is for recent steps in the current editing session. A named version is a checkpoint you want to find next week. The engine can create, list, restore, and delete versions when its storage adapter supports them:

const version = await engine.createVersion("Approved by client");
const versions = await engine.listVersions();

// Later, after the user chooses to restore it:
await engine.restoreVersion(version.id);

Restoring keeps an automatic copy of the current state first, then opens the older content as a new unsaved revision. That is different from moving a history pointer backward and erasing later work. The built-in storage adapters support versions; a custom backend needs the version methods described in the versions guide.

10. “How do I open my old Fabric.js JSON?”

You may already have designs saved with canvas.toJSON(). You do not have to throw them away to use a document format. The engine can import plain Fabric JSON from supported older versions and wrap it in a document:

await engine.importFabricJson(oldJsonText, {
  id: "imported-poster-42",
  metadata: { source: "previous editor" },
});

The format records a schemaVersion, canvas dimensions and background, objects in stacking order, assets, and document metadata. The migration guide covers Fabric 5, 6, and 7 JSON and schema errors. Test your own saved fixtures, especially if your old app had custom objects or unusual properties. The document format reference lists the fields.

11. “Can I safely open JSON uploaded by another user?”

A JSON file is input from outside your app. It may have unknown classes, unsafe addresses, extreme nesting, or far more objects than your browser can handle. The engine validates the document, refuses unsafe content, and applies object-count and depth limits before loading. Its security guide explains the checks and configuration.

This is a useful boundary, but it does not replace your application's authentication, authorization, upload limits, or server-side validation. Only load documents that the current user is allowed to access. If you render remote assets, still control which hosts your product trusts.

12. “Does it work with React, Next.js, Vue, or Svelte?”

The core package is framework independent. React has optional hooks for engine creation and toolbar state. Next.js needs the Fabric canvas created in the browser, not during server rendering. Vue should keep a Fabric canvas out of deep reactive proxies. Svelte and plain JavaScript can subscribe to the state store.

The package documents each setup: React, Next.js, Vue, Svelte, and plain JavaScript. These integrations connect the document engine to your app; they do not supply an editor UI.

What the package does not solve

A dependable article should say where the boundary is:

It does not draw or style your toolbar, selection controls, or pages. Fabric.js and your app own the canvas UI.
It does not provide a hosted database, image bucket, or backend authentication.
It does not make a deleted remote image available again or bypass CORS.
It does not provide real-time multi-user collaboration or automatic merge of two people's changes. A save conflict needs a product decision.
It does not export PDF directly. Use its image or SVG output with a separate PDF library if needed.
It does not promise that any particular issue in the Fabric.js tracker is fixed in Fabric.js itself. The package addresses the document workflow described here.

How to decide if you need it

If you only need to draw shapes and download a one-off image, Fabric.js may already be enough. If people will return to edit a saved design, ask three questions:

Can I identify the same object after reopening and undoing?
Can a failed load or a slow save erase good work?
Can I tell the user exactly why an image, font, or export failed?

If those matter, a document layer is worth considering. Start with the quick start, run the live examples, and test your own documents against the production checklist. The code is on GitHub, and the released package is on npm.

Test the failure, not just the happy path

Use a saved fixture that contains a group, a custom object, an image, and text in a web font. Then check these cases in your own app:

Save, refresh, and compare object IDs, stacking order, background, and metadata.
Undo a drag and a toolbar-driven change. Confirm each takes one step and the current object can be found by ID.
Delay two document loads. Confirm the later choice stays on screen.
Break an image URL. Confirm the old canvas stays visible and the missing URL is reported.
Delay a save, edit again, and confirm the final stored document contains the latest edit.
Open the same document in two tabs. Save in one, then confirm the other shows a conflict.
Make an unsaved edit, refresh, and check the recovery choice.
Try a remote image without CORS. Confirm export preflight reports the blocker.

These tests tell you whether the package and your storage, assets, and UI work together. A feature list alone cannot answer that.

Original sources and further reading

Fabric.js problem reports and official API

Package implementation and documentation

fabricjs-document-engine on npm and source repository
DocumentEngine API and error codes
Save/load, undo/redo, autosave, and assets/fonts
Recovery, versions, export, and document format

Editorial note: Use the problem phrases above because they describe the reader's task. No title, keyword placement, article length, or package mention guarantees a Google ranking. The working examples, clear limitations, and original issue context are what make this page useful.

How to Add a Production-Ready React Color Picker in 2026: Forms, Images, Eyedropper, Gradients & OKLCH

Sohail Khan — Thu, 24 Sep 2026 06:21:30 +0000

Adding a React color picker looks easy at first.

You install a component, pass it a color value, listen for changes, and you are done.

That works when all you need is a simple HEX color.

But real applications usually need more.

A settings page may need a color input that works with forms. A theme editor needs RGB and HSL controls. A design tool may need palettes, an eyedropper, gradients, or image color sampling. A modern design system may also need OKLCH and Display P3 instead of only HEX and RGB.

That is where a basic color input starts becoming a complete color workflow.

In this guide, I’ll show how to add a production-ready React color picker using ChromaPanel and gradually add the features that a real application may need.

ChromaPanel is an open-source React color picker with five picking modes, image sampling, an eyedropper, gradients, modern CSS color support, accessibility, native form behavior, TypeScript support, and zero runtime dependencies.

You can install it from npm and start with only a few lines of code.

Install the React color picker

Start by installing the package:

npm install chroma-panel

Then import ColorInput.

import { ColorInput } from "chroma-panel";

export function BrandColor() {
  return <ColorInput defaultValue="#3366cc" />;
}

That gives you a working React color input.

The user sees a color swatch. Clicking it opens the picker.

There is no provider to wrap around your application and no separate stylesheet required for the standard setup.

For a settings form or a simple customization page, this may already be enough.

Use a controlled React color picker

Most React applications eventually need the selected color somewhere else.

Maybe you want to update a preview, save a theme, change a button color, or store the value in your API.

In that case, use the normal controlled React pattern.

import { useState } from "react";
import { ColorInput } from "chroma-panel";

export function ThemeColor() {
  const [color, setColor] = useState("#7c3aed");

  return (
    <ColorInput
      value={color}
      onChange={(result) => setColor(result.hex)}
      aria-label="Theme color"
    />
  );
}

ChromaPanel supports both controlled and uncontrolled usage.

One useful detail is that onChange and onChangeComplete solve different problems.

onChange runs continuously while the user is changing the color.

onChangeComplete runs once when that interaction finishes.

<ColorInput
  value={color}
  onChange={(result) => setColor(result.hex)}
  onChangeComplete={(result) => saveTheme(result.hex)}
/>

That means you can update your UI instantly without making a database request on every tiny movement.

Use onChange for the live experience.

Use onChangeComplete for saving, network calls, history entries, or other expensive work.

Make the React color picker work with forms

This is one feature that often gets ignored when developers add a color picker.

A color picker is still an input.

If it is sitting inside a profile form, settings form, onboarding page, or admin panel, it should work with the rest of that form.

ChromaPanel's ColorInput can behave like a normal form field.

<form action={saveSettings}>
  <label htmlFor="brand-color">
    Brand color
  </label>

  <ColorInput
    id="brand-color"
    name="brandColor"
    defaultValue="#2563eb"
    format="hex"
    required
  />

  <button type="submit">
    Save settings
  </button>
</form>

The value can be submitted with the surrounding form.

It also supports things such as required, disabled, labels, form reset behavior, and different output formats.

You can read the full React color picker form guide if your application relies heavily on native forms or React form libraries.

This is useful for:

settings pages, theme configuration, SaaS dashboards, account customization, CMS interfaces, admin panels, and onboarding flows.

Show the full color picker inline

A popover works well when color is only one field in a larger form.

A design tool is different.

If users are working with color constantly, you probably want the panel to stay visible.

Use ChromaPanel directly.

import { ChromaPanel } from "chroma-panel";

export function ThemeEditor() {
  return (
    <ChromaPanel
      defaultValue="#3366cc"
      modes={["wheel", "sliders", "palettes"]}
      showTitleBar={false}
    />
  );
}

The ChromaPanel component gives you the same color system without hiding it inside a popover.

That works well for theme editors, website builders, design tools, brand editors, graphics applications, product customizers, and other interfaces where color is an important part of the workflow.

Choose the color picker modes you actually need

Not every user chooses color the same way.

Someone may want to explore visually.

Someone else knows the exact RGB value.

Another user only wants to select from approved brand colors.

ChromaPanel provides five different ways to choose a color.

The color wheel gives users a visual way to explore hue and saturation.

The RGB, HSL and HSB sliders provide precise channel-level control.

The palette mode provides searchable predefined colors and can also use your own brand palette.

The pencils mode provides a large 120-color swatch grid.

The image color picker lets users select colors from uploaded images.

You decide which ones should appear.

<ChromaPanel
  modes={[
    "wheel",
    "sliders",
    "palettes",
  ]}
/>

A simple settings page may only need the wheel.

A design tool may need all of them.

A company branding screen may only need an approved palette.

That is better than forcing every user to work with the same large interface.

Add an image color picker to React

This is where color picking becomes much more useful for creative applications.

Imagine a user uploads a logo.

They want the application theme to match that logo.

Instead of making them manually find each HEX value, the application can extract the dominant colors automatically.

ChromaPanel's image mode allows the user to drop, paste, or select an image.

The picker can extract dominant colors and show them as swatches.

The user can also sample an exact pixel.

<ChromaPanel
  modes={["image"]}
  defaultValue="#3366cc"
/>

You can also use the image API without showing the full React color picker.

import { extractPalette } from "chroma-panel";

const { swatches } = await extractPalette(file, {
  maxColors: 8,
});

That opens up other use cases.

You could generate a theme from a company logo.

You could create a palette from a product photograph.

You could extract avatar colors.

You could build image editing tools.

You could automatically suggest colors after a user uploads an asset.

The image sampler uses a bounded, downscaled sampling surface, and a separate worker entry point is available when you want heavier processing away from the main thread.

Add an eyedropper to your React color picker

Sometimes the color already exists somewhere on the screen.

The user simply wants to grab it.

ChromaPanel includes eyedropper support through the browser EyeDropper API.

Where the browser supports it, the user can choose a color from somewhere else on their screen.

This works especially well in:

design tools, website builders, theme editors, graphics applications, and brand customization interfaces.

You can use the eyedropper through the normal picker interface or use the useEyedropper hook when you want to create your own button.

Eyedropper support has also become a common feature in newer React color-picker components, which shows that developers increasingly expect precise screen sampling in advanced color workflows.

Add a gradient color picker

Solid colors are enough for many forms.

They are not enough for every design tool.

For gradients, ChromaPanel provides a separate GradientEditor.

import {
  GradientEditor,
  gradientToCss,
} from "chroma-panel/gradient";

It supports linear and radial gradients.

The gradient editor is separate from the normal color-picker entry point, so an application that only needs solid colors does not need to use the gradient functionality.

Keeping these features separate is useful because a production React color picker should not force every feature into every screen.

Gradient color pickers remain their own active search category in the React ecosystem, especially for design and customization tools.

Work with OKLCH and modern CSS colors

A few years ago, most web color interfaces stopped at:

HEX, RGB, HSL, and HSV.

Modern CSS has moved further.

OKLCH, OKLab, Lab, LCH, and Display P3 are increasingly useful in design systems and modern frontend work.

ChromaPanel includes CSS Color 4 utilities for those workflows.

import {
  parseColor,
  isInGamut,
  mapToGamut,
  serializeColor,
} from "chroma-panel/color";

const color = parseColor(
  "oklch(72% 0.18 250)"
);

if (color && !isInGamut(color, "srgb")) {
  const fallback = mapToGamut(
    color,
    "srgb"
  );

  console.log(
    serializeColor(fallback)
  );
}

These utilities can parse, convert, map, and serialize modern CSS colors.

They do not require the React UI.

That means the color engine can also be useful elsewhere in your application.

OKLCH is becoming a much more visible search topic around modern frontend color tooling, with current color tools and React packages specifically targeting OKLCH, gamut handling, Display P3, and modern design-system workflows.

Accessibility should be part of the color picker

A color picker is naturally visual.

That makes accessibility especially important.

Users should not need a mouse just to change a color.

ChromaPanel's accessibility implementation includes keyboard-operable controls and screen-reader behavior.

Color channels use real range inputs.

Keyboard users can change values with normal input behavior.

Focus is managed when the popover opens and closes.

Swatches have accessible names.

The component also accounts for reduced-motion and forced-color preferences.

Accessibility is also a common selling point in current React color-picker packages, so it is worth treating it as part of the component architecture instead of something added later.

Use ChromaPanel with Next.js

A modern React package also needs to work inside server-rendered applications.

ChromaPanel documents Next.js and server-rendering support.

Browser-dependent parts are separated so the package can be used safely in applications using React server rendering.

If the picker lives inside an interactive Next.js component, you can use it from a client component as expected.

"use client";

import { ColorInput } from "chroma-panel";

export function BrandColorPicker() {
  return (
    <ColorInput
      defaultValue="#3366cc"
    />
  );
}

This makes Next.js color picker another useful search path for developers who are not simply looking for a generic React component.

Use it with Tailwind CSS and shadcn/ui

Many React applications now build their UI around Tailwind CSS or shadcn/ui.

ChromaPanel has a Tailwind CSS styling guide and a dedicated shadcn/ui integration guide.

You are not required to install shadcn, Radix, or another UI library.

But if your application already uses them, you can make your existing Popover, Dialog, or Sheet own the surrounding interface and render ChromaPanel inside.

That matters because shadcn color picker is now a meaningful search category of its own. Current component libraries are publishing color-picker recipes specifically for shadcn and Next.js projects.

Keep your React color picker bundle under control

More features usually mean more JavaScript.

That is why entry points matter.

The full ChromaPanel configuration with all five modes is measured at about 23.1 kB gzipped in the project's Vite production measurement.

The panel shell plus one mode is around 15 kB gzipped.

If you only need one or two modes, import the panel shell and those modes explicitly.

import { ChromaPanel } from "chroma-panel/panel";
import { wheelMode } from "chroma-panel/modes";

export function SmallPicker() {
  return (
    <ChromaPanel
      modes={[wheelMode]}
    />
  );
}

You can read more about ChromaPanel entry points and tree shaking.

This is especially useful when you need the ChromaPanel API but not image picking, palettes, pencils, and every other mode.

When a smaller React color picker is better

More functionality is not automatically better.

If your requirement is simply:

“Let the user choose one HEX color.”

then you may not need image sampling, gradients, OKLCH, an eyedropper, palettes, or a complete color engine.

A smaller React color picker may be the better choice.

For example, react-colorful specifically focuses on providing a small, accessible, zero-dependency core picker. Its current npm documentation describes the picker as about 3.1 kB gzipped.

ChromaPanel makes more sense when your application needs the wider workflow.

The right question is not:

“Which React color picker has the most features?”

It is:

“What will users actually need to do with color in this application?”

A simple React color picker can grow with your app

You may start here:

<ColorInput
  defaultValue="#3366cc"
/>

Six months later, the same product may need:

a controlled color value, brand palettes, image sampling, recent colors, an eyedropper, precise RGB values, gradients, contrast checks, OKLCH, Tailwind tokens, and accessible keyboard controls.

Replacing your color system halfway through a product can create unnecessary work.

The idea behind ChromaPanel is that you can start small and add those capabilities only when you need them.

The package currently provides five color-selection modes, native forms, TypeScript, CSS Color 4 utilities, gradient editing, image sampling, contrast tools, exports, and zero runtime dependencies.

Frequently asked questions

What is a good React color picker for TypeScript?

ChromaPanel includes TypeScript types directly in the package, so you do not need a separate @types package.

You can see the TypeScript documentation for more details.

Can I use a React color picker with Next.js?

Yes. ChromaPanel includes documentation for Next.js and server rendering.

Interactive picker components should be used from the client side of a Next.js application.

Is there a React color picker with an eyedropper?

Yes. ChromaPanel includes eyedropper support where the browser EyeDropper API is available.

Can React pick colors from an image?

Yes. ChromaPanel's image color picker can extract dominant colors from an image and sample an exact pixel.

The extractPalette utility can also be used independently.

Is there a React gradient color picker?

ChromaPanel provides a separate GradientEditor for linear and radial gradient workflows.

Can I use OKLCH in a React color picker?

ChromaPanel's CSS Color 4 tools support OKLCH, OKLab, Lab, LCH, sRGB, and Display P3 workflows.

Does ChromaPanel work with Tailwind CSS?

Yes. There is a dedicated Tailwind CSS guide.

Can I use ChromaPanel with shadcn/ui?

Yes. The shadcn/ui integration guide shows how to use ChromaPanel with an existing shadcn interface.

Final thoughts

A React color picker can be a tiny control or a complete part of your product's design workflow.

For a basic HEX field, keep things simple.

But when users need precise values, palettes, an eyedropper, image sampling, gradients, accessibility, forms, modern CSS color spaces, or design-token workflows, building every part separately can become a much bigger task.

ChromaPanel brings those pieces together behind one React API while still letting you import only the parts you need.

If you want to try it:

Documentation: chroma-panel.jscrate.dev

npm: chroma-panel

GitHub: re-sohail/chroma-panel

The project is open source and released under the MIT license.

If you build something with it, find an issue, or have an idea for improving the React color picker experience, contributions and feedback are welcome.

ChromaPanel vs Other React Color Pickers: Features, Bundle Size, Accessibility, and More

Sohail Khan — Wed, 23 Sep 2026 06:47:11 +0000

Choosing a React color picker sounds simple until you start looking at what your application actually needs.

Maybe you only need a small HEX color picker.

Or maybe you need RGB and HSL controls, predefined palettes, an eyedropper, image color picking, gradients, accessibility, form support, and modern CSS colors like OKLCH.

Those are very different requirements.

There are several popular React color picker libraries available today, but they are not trying to solve exactly the same problem.

In this comparison, I’m looking at four options:

ChromaPanel, react-colorful, react-color, and @uiw/react-color.

The goal is not to say that one package should be used everywhere. Instead, I want to show what each React color picker provides, where the differences matter, and which kind of project each one fits.

React color picker comparison at a glance

The package and bundle figures below are based on the ChromaPanel comparison audit and the current package documentation. Bundle figures refer to the package main entry measured by Bundlephobia, which is different from the amount that a tree-shaken application may actually ship.

	ChromaPanel	react-colorful	react-color	@uiw/react-color
TypeScript	Included	Included	Separate types package	Included
Runtime dependencies	0	0	7	20 in main package
Main-entry gzip	~22 kB	~4.9 kB	~38.4 kB	~16 kB
Color wheel	Yes	Not	Not	Yes
RGB/HSL channel sliders	Yes	Limited	Limited	Limited
Alpha	Yes	Yes	Yes	Yes
Palettes/swatches	Yes	Recipe	Yes	Yes
Image color picker	Yes	Not	Not	Not
Eyedropper	Yes	Not	Not	Yes in Chrome picker
Gradient editor	Yes	Not	Not	Not
Modern CSS colors	Yes	Not	Not	Not
Form-ready input	Yes	Build yourself	Not	Not
Accessibility documented	Yes	Yes	Not	Limited documentation
Contrast tools	Yes	Not	Not	Not

The differences become more useful when we look at what those features actually mean inside a real React application.

1. ChromaPanel

Chroma Panel is the most feature-focused option in this comparison.

Instead of providing only one saturation area and a hue slider, it treats color selection as a larger UI problem.

You can use it as a simple React color input, but the same package can grow into a much more complete color system.

import { ColorInput } from "chroma-panel";

export function BrandColor() {
  return (
    <ColorInput
      defaultValue="#3366cc"
      aria-label="Brand color"
    />
  );
}

That is the basic version.

Behind it, ChromaPanel provides five different color-selection modes: wheel, sliders, palettes, pencils, and image picking. It also includes an eyedropper, native form behavior, CSS Color 4 utilities, gradients, contrast tools, TypeScript types, and zero runtime dependencies.

Five different ways to pick a color

A major difference is that ChromaPanel does not force every user into the same color picker interface.

The wheel is useful for visual color exploration.

The sliders provide precise RGB, HSL, and HSB controls.

Palettes work well when your product has approved or predefined colors.

Pencils provide a large 120-color swatch grid.

Image mode lets someone choose colors directly from a photo or image.

You can show all of them or choose only the modes your UI needs.

import { ChromaPanel } from "chroma-panel";

export function ThemeColorPicker() {
  return (
    <ChromaPanel
      defaultValue="#7c3aed"
      modes={["wheel", "sliders", "palettes"]}
    />
  );
}

This makes ChromaPanel useful when the same application has different color workflows.

For example, a settings form might use ColorInput, while a design editor can show the complete panel.

Pick colors from images

Image color picking is one of the bigger differences between ChromaPanel and the other React color picker libraries in this comparison.

A user can provide an image and pick an exact color from it.

ChromaPanel can also extract a palette from the image.

That can be useful when someone uploads a logo, product image, photograph, or brand asset and wants to create matching colors.

The other three libraries in this comparison do not currently document image color sampling as a built-in feature.

Eyedropper support

ChromaPanel supports the browser EyeDropper API.

When the browser supports it, the user can pick a color from elsewhere on their screen.

This works particularly well for design tools and theme editors.

There is an important limitation: the native EyeDropper API is browser-dependent, so this functionality is mainly available in Chromium-based browsers.

@uiw/react-color also exposes eyedropper functionality in its Chrome-style picker. Its own API includes a showEyeDropper option.

Modern CSS colors

This is an area where ChromaPanel takes a different approach from most traditional React color pickers.

It includes utilities for modern color spaces such as:

OKLCH, OKLab, Lab, LCH, Display P3, and sRGB.

That matters more now that modern CSS applications are increasingly using colors beyond the traditional HEX, RGB, and HSL formats.

You can parse a modern CSS color, check whether it fits inside a target gamut, map it when necessary, and serialize it again.

import {
  parseColor,
  isInGamut,
  mapToGamut,
  serializeColor,
} from "chroma-panel/color";

const color = parseColor("oklch(72% 0.18 250)");

if (color && !isInGamut(color, "srgb")) {
  const fallback = mapToGamut(color, "srgb");

  console.log(serializeColor(fallback));
}

The other React color pickers compared here do not currently document equivalent built-in CSS Color 4 support.

Gradient editing

ChromaPanel also provides a separate gradient editor.

import {
  GradientEditor,
  gradientToCss,
} from "chroma-panel/gradient";

You can work with linear and radial gradients while keeping that code separate from the basic color picker.

That separation is useful because projects that only need solid colors do not need to use the gradient functionality.

Form support

This feature is easy to overlook.

A color picker often ends up inside a form.

ChromaPanel's ColorInput behaves more like a real form field.

<form>
  <ColorInput
    name="brandColor"
    defaultValue="#2563eb"
    required
  />

  <button type="submit">Save</button>
</form>

The selected value can participate in form submission, native validation, and form reset behavior.

With smaller color picker libraries, you will often connect the picker to your form state yourself.

Neither approach is wrong, but having the behavior built in removes some repeated application code.

Accessibility

Color pickers are visual components, but they should not require a mouse.

ChromaPanel documents keyboard and screen-reader behavior and uses native range inputs for color axes.

react-colorful also specifically documents accessibility and says it follows WAI-ARIA guidelines.

That makes these two worth looking at closely when accessibility is an important requirement.

Contrast checking

ChromaPanel also includes contrast-related utilities.

The documentation covers WCAG contrast, alpha-aware checks, APCA, and color suggestions.

This means the color picker can be connected to workflows such as choosing a background color and immediately checking whether text will remain readable.

That is particularly useful for theme builders and design systems.

2. react-colorful

react-colorful takes almost the opposite approach.

Its biggest strength is simplicity and size.

The package describes itself as a tiny React and Preact color picker. It has zero dependencies, includes TypeScript types, supports accessibility, and provides multiple picker components for HEX, RGB, HSL, HSV, and their alpha variants.

A basic example is very small:

import { HexColorPicker } from "react-colorful";

function Picker() {
  const [color, setColor] = useState("#aabbcc");

  return (
    <HexColorPicker
      color={color}
      onChange={setColor}
    />
  );
}

Its README quotes roughly 3.1 kB gzipped for a picker, while the comparison audit measured about 4.9 kB for the package main entry. Those numbers measure different things, so they should not be treated as a contradiction.

This is one of the main reasons react-colorful is so attractive.

You get a focused React color picker without bringing in a large feature set.

It supports saturation, hue, alpha, several color formats, touch devices, accessibility, and TypeScript.

What it does not try to provide is equally important.

Things such as palettes and a popover are shown as recipes rather than being the main responsibility of the package. Image sampling, gradients, modern CSS color spaces, and an eyedropper are not documented as built-in features.

So if you need a compact color control and you are happy building the surrounding UI yourself, react-colorful remains a very strong option.

3. react-color

react-color follows a different idea again.

Instead of concentrating on one small picker, it provides 13 different picker designs, including Sketch, Photoshop, Chrome, Material, Circle, Block, Twitter, GitHub, and others.

A typical example looks like this:

import { SketchPicker } from "react-color";

function Picker() {
  return <SketchPicker />;
}

That can be useful when you want an interface that already looks familiar.

Instead of designing a complete color-picker layout yourself, you can choose one of the existing styles.

The trade-off is that react-color is an older package.

npm currently lists version 2.19.3, and that release was published years ago. Its TypeScript definitions are provided separately, and the comparison audit records seven runtime dependencies and a larger main-entry bundle than the other packages shown here.

That does not make the package unusable.

It simply means maintenance history and architecture are worth considering before introducing it into a new React project.

For an existing application that already uses react-color, replacing it only because another library is newer may also create unnecessary work.

4. @uiw/react-color

@uiw/react-color sits somewhere between the previous approaches.

It offers many different React color picker components, but those components can also be installed separately.

Its collection includes options such as Sketch, Chrome, Wheel, Swatch, Slider, Material, Compact, Circle, Block, GitHub, and Colorful. It also provides lower-level pieces such as saturation, hue, alpha, editable inputs, and shade sliders.

That modular structure is useful.

If your project only needs the wheel, for example, you do not necessarily have to build everything around the main package.

npm install @uiw/react-color-wheel

The main @uiw/react-color package currently lists 20 dependencies, but those are largely its own component packages. Installing an individual picker can therefore make more sense when you only need one part of the library.

It also includes TypeScript declarations.

One interesting feature is the Chrome picker's eyedropper option.

<Chrome
  showEyeDropper
  color={color}
  onChange={handleChange}
/>

The package also provides editable HEXA, RGBA, and HSLA input modes.

If you prefer having many independent picker styles available as separate packages, @uiw/react-color provides a lot of flexibility.

ChromaPanel vs react-colorful

This is probably the most useful direct comparison.

Both libraries have zero runtime dependencies.

Both include TypeScript types.

Both document accessibility.

But their goals are quite different.

react-colorful focuses on doing the core color-picker job with very little code.

ChromaPanel includes a much larger set of functionality around that picker.

With ChromaPanel, you can get the wheel, per-channel RGB/HSL/HSB sliders, palettes, image sampling, eyedropper, gradients, form integration, contrast utilities, and modern CSS colors from the same project.

With react-colorful, you get a significantly smaller foundation and can build the extra pieces your application needs.

So the real question is not simply:

Which React color picker is smaller?

That answer is clearly react-colorful.

The more useful question is:

How much color functionality does my application actually need?

If the answer is only a simple HEX, RGB, HSL, or HSV picker, the smaller package can make a lot of sense.

If the answer includes several additional color workflows, comparing only the size of the base picker becomes less useful.

ChromaPanel vs react-color

These two packages are also quite different.

react-color gives you many recognizable pre-designed picker interfaces.

ChromaPanel instead provides different ways of working with color inside one system.

If you specifically want something that looks like the classic Sketch or Photoshop picker, react-color already gives you that type of interface.

ChromaPanel focuses more on modern application features: image sampling, CSS Color 4, form behavior, accessibility, gradients, contrast calculations, an eyedropper, and different selection modes.

Another difference is package age and maintenance.

react-color has existed for many years and has a very large usage history. ChromaPanel is much newer, so it does not yet have that same long-term ecosystem history.

That history can matter when evaluating a dependency, and it is worth considering alongside features.

ChromaPanel vs @uiw/react-color

This comparison is closer because both provide several ways to choose colors.

@uiw/react-color gives developers a large collection of separate picker components.

ChromaPanel gives developers multiple modes inside one color panel.

@uiw/react-color has a dedicated wheel, swatches, Chrome-style picker, Sketch-style picker, sliders, and lower-level primitives.

ChromaPanel adds areas such as image color extraction, modern CSS color spaces, native form integration, contrast utilities, and a dedicated gradient editor.

Both approaches can work well.

The main difference is whether you want a collection of separate picker packages or one color system that can switch between different modes.

What about bundle size?

Bundle size deserves some context.

The comparison audit measured the package main entries at roughly:

ChromaPanel: 22.0 kB gzip → @uiw/react-color: 16.0 kB → react-colorful: 4.9 kB → react-color: 38.4 kB.

But those numbers are not the complete story.

react-colorful documents a smaller figure for an individual picker.

@uiw/react-color allows individual picker packages to be installed separately.

ChromaPanel also provides smaller entry points so applications do not have to use all five modes.

Its own Vite measurement reports around 23.1 kB gzipped for all five modes and roughly 15 kB for the panel shell plus one mode.

That is why bundle comparisons should always include the functionality being shipped.

A 5 kB package plus several custom components may not remain 5 kB once the full feature is finished.

At the same time, an application that genuinely needs only a simple color picker should not ship advanced functionality it will never use.

Which React color picker should you use?

There is no single answer for every project.

Use ChromaPanel when your application needs a broader color system: multiple selection modes, image color picking, an eyedropper, palettes, gradients, modern CSS colors, form behavior, accessibility, and contrast utilities.

Use react-colorful when you mainly want a small, accessible React color picker and prefer to build additional UI such as popovers and palettes yourself.

Use react-color when its collection of familiar ready-made picker designs matches an existing application or a specific UI requirement.

Use @uiw/react-color when you want a collection of modular picker components and like being able to install individual styles such as Wheel, Chrome, Sketch, or Swatch separately.

That is a more useful way to compare React color picker libraries than simply asking which package has the most features or the smallest bundle.

Final thoughts

A React color picker can be a tiny input or a surprisingly large part of an application's design system.

That is why these four libraries look so different.

react-colorful keeps the core small.

react-color gives you many familiar picker designs.

@uiw/react-color provides a modular collection of individual picker components.

And ChromaPanel tries to cover the wider color workflow in one package: wheel, sliders, palettes, pencils, image sampling, eyedropper, gradients, accessibility, form integration, contrast tools, and modern CSS color spaces.

For a simple HEX field, you may not need all of that.

But for a theme editor, website builder, design tool, branding interface, SaaS dashboard, product customizer, or application where users work seriously with color, those additional features can save a lot of custom implementation.

The important thing is to choose the React color picker based on the experience you need to build.

Not just the name of the package.

ChromaPanel: A Modern React Color Picker with Eyedropper, Image Sampling, Gradients, and More

Sohail Khan — Wed, 23 Sep 2026 06:03:21 +0000

A color picker looks like a simple UI component until you need to use one in a real product.

At first, you may only need a HEX color field.

Then the requirements start growing.

Users want a color wheel. Designers want exact RGB and HSL values. Your settings page needs predefined brand colors. Someone asks to pick a color from an uploaded image. Another user wants an eyedropper. Your form needs validation. Keyboard navigation has to work. And eventually you may need gradients, OKLCH, Display P3, or accessible contrast checks.

At that point, a basic React color picker is no longer enough.

That is the problem I wanted to solve with ChromaPanel.

ChromaPanel is an open-source React color picker built for forms, settings pages, toolbars, theme editors, design tools, and other interfaces where users need more than a simple HEX picker.

It gives you multiple ways to choose a color while keeping them behind one React API.

What is ChromaPanel?

ChromaPanel is a React color picker component that can be used as a small color input or as a complete inline color panel.

It includes:

a color wheel
RGB, HSL, HSB/HSV, and alpha sliders
searchable color palettes
a 120-color pencil-style swatch grid
image color extraction and pixel sampling
an eyedropper in supported browsers
HEX, RGB, HSL, HSV, and alpha values
controlled and uncontrolled React state
native form support
keyboard and screen-reader support
TypeScript types
CSS Color 4 utilities
OKLCH, OKLab, Lab, LCH, sRGB, and Display P3 support
linear and radial gradient editing
contrast helpers
CSS, SCSS, Tailwind, and design-token exports
zero runtime dependencies

You can use everything together or only import the parts your application needs.

Install the React color picker

Getting started is intentionally simple.

npm install chroma-panel

There is no provider that you need to add around your application.

There is also no separate CSS file you need to import for the standard setup.

Once the package is installed, you can render a working React color picker with ColorInput.

import { ColorInput } from "chroma-panel";

export function BrandColor() {
  return <ColorInput defaultValue="#3366cc" />;
}

ColorInput displays a color swatch and opens ChromaPanel in a popover when the user clicks it.

For many forms and settings pages, that may be all you need.

Using ChromaPanel as a controlled React color picker

Most real applications need to keep the selected color in React state.

ChromaPanel supports the normal controlled component pattern.

import { useState } from "react";
import { ColorInput } from "chroma-panel";

export function AccentColorPicker() {
  const [color, setColor] = useState("#3366cc");

  return (
    <ColorInput
      value={color}
      onChange={(result) => setColor(result.hex)}
      aria-label="Accent color"
    />
  );
}

The useful part here is that onChange does not only give you a HEX string.

The result contains different representations of the selected color, so your application can use the format it actually needs.

You can update a live preview with onChange while the user is dragging and use onChangeComplete when the interaction finishes.

<ColorInput
  value={color}
  onChange={(result) => setColor(result.hex)}
  onChangeComplete={(result) => saveColor(result.hex)}
/>

This is useful when saving the value makes a network request, creates an undo entry, updates a database, or runs another expensive operation.

The UI can remain responsive without sending a request for every tiny movement of the color picker.

Need an inline color picker instead?

Sometimes a popover is not the right UI.

A design editor, theme builder, drawing tool, or customization page may need the entire React color picker to stay visible.

That is what ChromaPanel is for.

import { ChromaPanel } from "chroma-panel";

export function ThemeEditor() {
  return (
    <ChromaPanel
      defaultValue="#3366cc"
      modes={["wheel", "sliders", "palettes"]}
    />
  );
}

The modes property is important.

You do not have to show every feature just because the package supports it.

A branding form may only need palettes.

A design tool may need sliders, a wheel, and image sampling.

A simple theme editor may only need the wheel.

This makes it possible to use the same color picker package across different parts of an application without giving every user the same large interface.

Color wheel

The wheel gives users a visual way to explore colors.

Instead of typing values, they can move around the hue wheel and adjust the color visually.

This works well when choosing colors is part of a creative interface such as a theme editor, website builder, drawing tool, product customizer, or design system.

It is also useful when users know roughly what color they want but do not know its HEX or RGB value.

RGB, HSL and HSB sliders

Sometimes visual selection is not precise enough.

Developers and designers often need exact channel values.

ChromaPanel includes per-channel controls for RGB, HSL, HSB/HSV, and alpha.

That means someone can visually find a color first and then fine-tune the exact numbers without switching to another tool.

The same React color picker can therefore work for casual users and people who need precise color control.

Searchable color palettes

Many applications should not allow completely arbitrary colors.

A company may have an approved brand palette. A theme builder may provide a set of design tokens. A product customizer may only support colors that can actually be manufactured.

ChromaPanel supports named palettes and searchable swatches, so you can provide those approved colors directly inside the picker.

Instead of building a separate palette component beside your color picker, both experiences can live inside the same UI.

The 120-color pencils mode

Pencils mode provides a large grid of ready-made colors.

Despite the name, it is not a drawing tool. It is a quick color-selection interface inspired by physical sets of colored pencils.

There are 120 colors available by default, and the set can be replaced when your product needs something different.

This mode is useful when users want to explore many predefined colors quickly without working with sliders or numerical values.

Pick colors from an image

This is one of the areas where a simple React color picker can quickly become a much bigger feature.

Imagine a user uploads a company logo and wants to create a matching theme.

Or they upload a product photo and want to use one of its main colors.

With ChromaPanel's image mode, a user can drop, paste, or select an image.

The React color picker can extract dominant colors from that image and display them as swatches.

The user can also select an exact pixel from the image.

You can use the image extraction API without showing the full color picker as well.

import { extractPalette } from "chroma-panel";

const { swatches } = await extractPalette(file, {
  maxColors: 8,
});

This makes the same functionality useful for automatic theme generation, logo analysis, image editors, design applications, avatar customization, and other tools.

Image processing is bounded and downscaled rather than processing an unlimited full-size image directly.

There is also a separate worker entry point for applications that want to move heavier image processing away from the main thread.

A React color picker with an eyedropper

ChromaPanel also includes support for the browser EyeDropper API.

Where that browser API is available, users can pick a color from somewhere else on their screen.

This can be especially useful inside design tools, theme builders, website editors, and other visual applications.

The important part is that unsupported browsers do not need special handling from your UI just to hide the normal picker control.

There is also a useEyedropper hook if you want to create your own eyedropper button somewhere else in your interface.

It behaves like a real form control

A surprisingly important part of a React color picker is how it works inside forms.

You should not have to create hidden inputs, manually synchronize values, and rebuild standard browser behavior just because the input happens to select a color.

ColorInput can take a name and submit its value with FormData.

<form action={saveProfile}>
  <label htmlFor="profile-color">Profile color</label>

  <ColorInput
    id="profile-color"
    name="profileColor"
    defaultValue="#3366cc"
    format="hex"
    required
  />

  <button type="submit">Save</button>
</form>

It also supports normal behaviors such as required, disabled, and form.reset().

That makes ChromaPanel particularly useful for settings screens, account customization, admin panels, SaaS dashboards, onboarding forms, and theme settings.

Accessibility is part of the component

Color pickers can be difficult to make accessible.

Many visual pickers are built almost entirely around pointer interactions. That works with a mouse, but it can become frustrating or impossible with a keyboard or screen reader.

ChromaPanel uses real range inputs for its color axes.

That allows standard browser keyboard behavior to do much of the work.

Arrow keys can change values. Page Up and Page Down make larger movements. Home and End move to the limits.

Values are announced with meaningful text rather than exposing only an unexplained number.

The popover manages focus, closes with Escape, and returns focus to its trigger.

Swatches use buttons with accessible names, and the component also respects reduced-motion and forced-color preferences.

Accessibility should not be something that gets added after a React color picker is already built. It affects the way the component itself should work.

Modern CSS colors: OKLCH, OKLab and Display P3

HEX and RGB are still everywhere, but modern CSS supports much more.

ChromaPanel includes color utilities for working with:

OKLCH, OKLab, Lab, LCH, sRGB, and Display P3.

For example:

import {
  parseColor,
  isInGamut,
  mapToGamut,
  serializeColor,
} from "chroma-panel/color";

const brand = parseColor("oklch(72% 0.18 250)");

if (brand && !isInGamut(brand, "srgb")) {
  const fallback = mapToGamut(brand, "srgb");

  console.log(serializeColor(fallback));
}

These utilities do not require React or the DOM.

They can therefore also be used as general TypeScript color utilities inside your application.

This becomes useful when building design systems that are moving toward OKLCH, wide-gamut colors, and modern CSS color workflows.

A gradient color picker for React

Solid colors are not always enough either.

ChromaPanel provides a separate GradientEditor entry point for building linear and radial gradients.

import {
  GradientEditor,
  gradientToCss,
} from "chroma-panel/gradient";

Gradient stops can be changed with the keyboard, and the utilities can turn the gradient model back into CSS.

The gradient tools are kept in a separate entry point.

That means an application that only needs a solid React color picker does not need to include the gradient editor code.

This separation matters because feature-rich UI libraries should not force every feature into every bundle.

Zero runtime dependencies

ChromaPanel has no runtime dependencies.

React and React DOM are peer dependencies, meaning the package uses the React installation that already exists in your application.

TypeScript declarations are included as well, so there is no separate @types package to install.

It supports React 16.14 and newer, including React 19.

It also provides ESM and CommonJS builds.

What about bundle size?

This is an important trade-off.

ChromaPanel is not trying to be the smallest React color picker on npm.

The complete package gives you much more functionality than a basic saturation box and hue slider.

With all five modes, the measured addition to a Vite production build is about 23.1 kB gzipped.

Using the panel shell with one mode is around 15 kB gzipped.

If your application only needs a tiny HEX picker, a smaller library such as react-colorful can make more sense.

But if your application would otherwise need a color picker, separate palettes, an eyedropper implementation, an image color picker, gradient editing, color conversions, accessibility work, and form integration, comparing only the size of the basic picker does not tell the full story.

Import only the modes you need

If you do not need all five modes, you can use the smaller entry points.

import { ChromaPanel } from "chroma-panel/panel";
import { wheelMode } from "chroma-panel/modes";

export function SimplePicker() {
  return <ChromaPanel modes={[wheelMode]} />;
}

This is useful when you want ChromaPanel's API and behavior without including every available color-selection mode.

Works with modern React stacks

ChromaPanel is not tied to one UI framework.

The documentation includes guidance for Next.js, Vite, Remix, shadcn/ui, Material UI, React Aria, React Hook Form, Tailwind CSS, and server-rendered applications.

For example, if your project already uses shadcn/ui, you can let shadcn's Popover, Dialog, or Sheet own the surrounding interface and render ChromaPanel inside it.

ChromaPanel does not require shadcn/ui, Radix UI, or Base UI as dependencies.

That is useful when you want a React color picker that fits your existing design system rather than forcing another UI framework into the application.

When ChromaPanel makes sense

I built ChromaPanel for applications where color selection is part of the product rather than just a small decorative field.

If you are building a theme editor, design system, SaaS settings page, website builder, graphics tool, product customizer, brand editor, admin dashboard, CMS, or another interface with serious color controls, having these capabilities behind one API can remove a lot of custom work.

But there is an equally important point.

If your entire requirement is simply:

“Let the user choose a HEX color.”

then you probably do not need every feature ChromaPanel provides.

A smaller React color picker can be the right choice.

Choosing a library should be based on what your interface actually needs, not the number of features printed on its README.

Why I built it

The main idea behind ChromaPanel was not to build another variation of the same basic React color picker.

It was to create a color-selection component that could grow with a real application.

You can start with:

<ColorInput defaultValue="#3366cc" />

and stop there.

Or the same project can later add palettes, image sampling, precise sliders, gradients, modern CSS color spaces, accessibility helpers, contrast tools, and custom modes without replacing the original color picker.

That flexibility is what I wanted from the package.

Final thoughts

There are already good React color picker libraries available, and ChromaPanel is not meant to replace every one of them.

Its focus is different.

It is for applications that need several ways to work with color but still want one consistent React API.

If you need a React color picker with a color wheel, RGB and HSL sliders, palettes, image color extraction, an eyedropper, gradients, modern CSS colors, TypeScript support, accessibility, and zero runtime dependencies, ChromaPanel may be worth trying.

The project is open source and released under the MIT license.

If you use it in a project, find a problem, or have an idea for something that could make the React color picker better, feedback and contributions are welcome.

A Better React Color Picker: Why I Switched to Chroma Panel

Sohail Khan — Mon, 21 Sep 2026 09:00:34 +0000

Finding a good React color picker is harder than it should be.

If you search for one right now, you mostly find the same old packages. They work, but they are very basic. Most of them just give you a simple box to pick a color.

But what if you need more? Sometimes your users need to pick colors from an image, use a color wheel, or choose from a custom brand palette. Building these extra features yourself takes a lot of time.

Recently, I found a new npm package called Chroma Panel. It solves all these problems. Here is why I started using it in my React projects instead of the older libraries.

More Than Just a Basic Picker

Chroma Panel gives you a lot of advanced tools right out of the box. You do not have to write custom code to get them working.

Here are the main features it includes:

Color Wheel: A nice, smooth circle to pick exact colors.
Sliders: Easy sliders to change hue, saturation, lightness, and transparency.
Image Picker: Users can upload an image and pick a color straight from the picture.
Palettes: You can set up custom color swatches for your users to pick from.
Pencil Mode: A drawing tool feature.
Custom Modes: You can change the layout to fit exactly what your app needs.

Amazing Documentation (Like Shadcn UI)

My favorite thing about Chroma Panel is the documentation.

We all hate when a package has bad docs. But the Chroma Panel website looks and feels like modern docs, very similar to Shadcn UI or Base UI.

They explain everything in plain English. You get:

Clear, step-by-step guides on how to install it.
Code examples that you can just copy and paste.
Details on how to use their custom React hooks.
Examples of how to set up every single feature.

How to Set It Up

It is very easy to use. First, install the package in your terminal:

npm install chroma-panel

Then, you just bring it into your React component. Here is a simple example to show how it works:

import { useState } from "react";
import { ChromaPanel } from "chroma-panel";


export default function MyColorPicker() {
  const [myColor, setMyColor] = useState("#ff0000");

  return (
    <div>
      <h3>Pick a Color</h3>

      <ChromaPanel 
        color={myColor} 
        onChange={(newColor) => setMyColor(newColor.hex)} 
      />

      <p>The hex code is: {myColor}</p>
    </div>
  );
}

That is all you need to get a great-looking color picker on your screen.

Try It Out

If you are starting a new React project, or if you want to replace an old, boring color picker, you should check this one out. It saves a lot of time and makes your app look much better.

You can learn more about it at these links:

Read the Docs: https://chroma-panel.jscrate.dev/
NPM Page: https://www.npmjs.com/package/chroma-panel

Let me know in the comments what color picker you normally use!

DEV Community: Sohail Khan

Why Fabric.js `loadFromJSON` Can Leave Your Editor Half-Loaded

Does a failed image always leave Fabric.js partially loaded?

Why can a valid canvas JSON file still fail to reopen?

Why does clearing the canvas before loading make failures worse?

What happens before the engine mutates the canvas content?

How do you prove that a failed image leaves the current drawing intact?

How do you show the engine error in a React editor?

Should you catch errors or subscribe to load:error?

How do you repair a missing image without removing the object?

What if the image URL expires instead of disappearing?

Can you fix an image CORS failure from React alone?

What should the editor do with each loading error?

Will awaiting loadFromJSON solve every loading problem?

How do you keep an older load from replacing a newer document?

Save Fabric.js Canvas JSON to an API and Open It by Document ID

What should you save to reopen an editable Fabric.js canvas?

What is the storage adapter contract?

How do you connect the document engine to an HTTP API?

How do you save and open a document in React?

What does the app-owned HTTP endpoint look like?

How does a revision check prevent lost updates?

Are image files stored inside the canvas JSON?

What should you check before shipping this save flow?

Can you use MongoDB, MySQL, or a different backend?

Can you open JSON saved by an older Fabric.js editor?

Does calling toDocument() mean the canvas has been saved?

Fabric.js Editor Problems: Save, Load, Undo, Autosave, and Recovery

The short answer

Start with a canvas and a document

1. “Fabric.js undo redo not working”

2. “Fabric.js object reference lost after undo or reload”

3. “Fabric.js custom properties lost after JSON load”

4. “Fabric.js loadFromJSON failed” or “the old canvas disappeared”

5. “Fabric.js autosave overwrites newer changes”

Put the same save rules on your backend

6. “Fabric.js image missing after load” and “my font changed”

7. “Fabric.js canvas lost after refresh or crash”

8. “Fabric.js tainted canvas cannot be exported”

9. “How do I keep versions of a Fabric.js design?”

10. “How do I open my old Fabric.js JSON?”

11. “Can I safely open JSON uploaded by another user?”

12. “Does it work with React, Next.js, Vue, or Svelte?”

What the package does not solve

How to decide if you need it

Test the failure, not just the happy path

Original sources and further reading

How to Add a Production-Ready React Color Picker in 2026: Forms, Images, Eyedropper, Gradients & OKLCH

Install the React color picker

Use a controlled React color picker

Make the React color picker work with forms

Show the full color picker inline

Choose the color picker modes you actually need

Add an image color picker to React

Add an eyedropper to your React color picker

Add a gradient color picker

Work with OKLCH and modern CSS colors

Accessibility should be part of the color picker

Use ChromaPanel with Next.js

Use it with Tailwind CSS and shadcn/ui

Keep your React color picker bundle under control

When a smaller React color picker is better

A simple React color picker can grow with your app

Frequently asked questions

What is a good React color picker for TypeScript?

Can I use a React color picker with Next.js?

Is there a React color picker with an eyedropper?

Can React pick colors from an image?

Is there a React gradient color picker?

Can I use OKLCH in a React color picker?

Does ChromaPanel work with Tailwind CSS?

Can I use ChromaPanel with shadcn/ui?

Final thoughts

ChromaPanel vs Other React Color Pickers: Features, Bundle Size, Accessibility, and More

React color picker comparison at a glance

1. ChromaPanel

Five different ways to pick a color

Pick colors from images

Eyedropper support

Modern CSS colors

Should you catch errors or subscribe to `load:error`?

Will awaiting `loadFromJSON` solve every loading problem?

Does calling `toDocument()` mean the canvas has been saved?