From 6f36c4f8e9867447874eb96b6c0dee2b04de5c74 Mon Sep 17 00:00:00 2001
From: Murilo Cruz <murilomecr@gmail.com>
Date: Wed, 14 Oct 2026 16:47:27 -0300
Subject: [PATCH 1/2] feat: native lazy loading for images (#300)

Add an opt-in `lazyLoading` config param that sets the native
loading="lazy" attribute on images, so they're only fetched when they
approach the viewport.

Native lazy loading never fires for images that aren't rendered, so:
- while a lazy image is pending, the block stays in the "uploading"
  state, showing the preloader as a placeholder
- in the "uploading" state the picture is kept in the layout (invisible)
  instead of display: none
- Ui.render() no longer resets a status set before rendering to "empty"

Videos (.mp4) are still loaded immediately.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md          | 30 ++++++++++++++++++++++++++++++
 dev/index.html     | 19 +++++++++++++++++++
 src/index.css      | 10 +++++++++-
 src/index.ts       |  1 +
 src/types/types.ts |  7 +++++++
 src/ui.ts          | 27 ++++++++++++++++++++++++++-
 6 files changed, 92 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 39e29a2..d3d32b8 100644
--- a/README.md
+++ b/README.md
@@ -84,6 +84,7 @@ Image Tool supports these configuration parameters:
 | uploader | `{{uploadByFile: function, uploadByUrl: function}}` | Optional custom uploading methods. See details below. |
 | actions | `array` | Array with custom actions to show in the tool's settings menu. See details below. |
 | features | `object` | Allows you to enable/disable additional features such as border, background tunes and caption. See details below. |
+| lazyLoading | `boolean` | (default: `false`) Defers loading of images until they approach the viewport, using native `loading="lazy"`. See details below. |
 
 Note that if you don't implement your custom uploader methods, the `endpoints` param is required.
 
@@ -295,3 +296,32 @@ var editor = EditorJS({
   ...
 });
 ```
+
+## Lazy loading images
+
+Set `lazyLoading` to `true` to load images only when they approach the viewport, using the browser's native `loading="lazy"`. It's useful for long documents with many images, or for images served by private or paid endpoints. A preloader is shown in place of each image until it's loaded.
+
+```js
+import ImageTool from '@editorjs/image';
+
+var editor = EditorJS({
+  ...
+
+  tools: {
+    ...
+    image: {
+      class: ImageTool,
+      config: {
+        /**
+         * Load images only when they approach the viewport
+         */
+        lazyLoading: true,
+      }
+    }
+  }
+
+  ...
+});
+```
+
+Lazy loading applies to images only. `.mp4` sources are still loaded immediately.
diff --git a/dev/index.html b/dev/index.html
index 2383256..295c04b 100644
--- a/dev/index.html
+++ b/dev/index.html
@@ -10,6 +10,23 @@
     <script src="https://cdn.jsdelivr.net/npm/@editorjs/editorjs@latest"></script>
     <script type="module">
       import ImageTool from "../src/index.ts";
+
+      /**
+       * Long document to test lazy loading: watch the Network tab while scrolling
+       */
+      const lazyBlocks = Array.from({ length: 15 }, (_, i) => [
+        {
+          type: "paragraph",
+          data: { text: `Image #${i + 1} below` },
+        },
+        {
+          type: "image",
+          data: {
+            file: { url: `https://picsum.photos/id/${10 + i}/1200/800` },
+            caption: `picsum #${10 + i}`,
+          },
+        },
+      ]).flat();
       const editor = new EditorJS({
         holder: "editorjs",
         data: {
@@ -28,6 +45,7 @@
                 caption: "kimitsu no yayiba",
               },
             },
+            ...lazyBlocks,
           ],
         },
 
@@ -45,6 +63,7 @@
                 background: false,
                 stretch: true,
               },
+              lazyLoading: true,
             },
           },
         },
diff --git a/src/index.css b/src/index.css
index 55342ef..f01ed31 100644
--- a/src/index.css
+++ b/src/index.css
@@ -116,9 +116,17 @@
       display: flex;
       border: 1px solid var(--border-color);
       background-color: #fff;
+      position: relative;
 
+      /**
+       * Keep the picture in the layout (but invisible) instead of display: none,
+       * so native lazy loading (loading="lazy") can detect when it approaches the viewport
+       */
       &-picture {
-        display: none;
+        position: absolute;
+        top: 0;
+        left: 0;
+        visibility: hidden;
       }
     }
 
diff --git a/src/index.ts b/src/index.ts
index 7700606..c40d462 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -108,6 +108,7 @@ export default class ImageTool implements BlockTool {
       uploader: config.uploader,
       actions: config.actions,
       features: config.features || {},
+      lazyLoading: config.lazyLoading,
     };
 
     /**
diff --git a/src/types/types.ts b/src/types/types.ts
index 3de5505..09a6501 100644
--- a/src/types/types.ts
+++ b/src/types/types.ts
@@ -199,6 +199,13 @@ export interface ImageConfig {
    * Tunes to be enabled.
    */
   features?: FeaturesConfig;
+
+  /**
+   * Enables native lazy loading for images (loading="lazy").
+   * When true, images are only fetched when they approach the viewport.
+   * @default false
+   */
+  lazyLoading?: boolean;
 }
 
 /**
diff --git a/src/ui.ts b/src/ui.ts
index f66afa0..9f1292b 100644
--- a/src/ui.ts
+++ b/src/ui.ts
@@ -165,7 +165,15 @@ export default class Ui {
    * Renders tool UI
    */
   public render(): HTMLElement {
-    this.toggleStatus(UiState.Empty);
+    /**
+     * Keep the status set before rendering (e.g. "uploading" while a lazy image is pending),
+     * otherwise the hidden image container would never let the lazy image load
+     */
+    const hasStatus = Object.values(UiState).some(state => this.nodes.wrapper.classList.contains(`${this.CSS.wrapper}--${state}`));
+
+    if (!hasStatus) {
+      this.toggleStatus(UiState.Empty);
+    }
 
     return this.nodes.wrapper;
   }
@@ -225,6 +233,23 @@ export default class Ui {
        * Change event to be listened
        */
       eventName = 'loadeddata';
+    } else if (this.config.lazyLoading === true) {
+      /**
+       * Let the browser defer fetching until the image approaches the viewport
+       */
+      attributes.loading = 'lazy';
+
+      /**
+       * Re-add src after loading: some browsers start fetching as soon as src is set
+       */
+      delete attributes.src;
+      attributes.src = url;
+
+      /**
+       * Show the preloader as a placeholder until the image is loaded.
+       * The image stays in the layout (but invisible) while uploading, so native lazy loading can trigger
+       */
+      this.toggleStatus(UiState.Uploading);
     }
 
     /**

From 5fcfc124dbf04ce1348af553c46aa92b562cb3d4 Mon Sep 17 00:00:00 2001
From: Murilo Cruz <murilomecr@gmail.com>
Date: Wed, 14 Oct 2026 17:00:51 -0300
Subject: [PATCH 2/2] fix: fall back to empty state when a lazy image fails to
 load

Without this, a lazy image with a broken URL kept the block in the
"uploading" state, showing the preloader forever with no way to select
another image. Now it behaves like a failed non-lazy image.

Also add a broken image to the playground to test it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dev/index.html | 11 +++++++++++
 src/ui.ts      | 10 ++++++++++
 2 files changed, 21 insertions(+)

diff --git a/dev/index.html b/dev/index.html
index 295c04b..593b4cc 100644
--- a/dev/index.html
+++ b/dev/index.html
@@ -46,6 +46,17 @@
               },
             },
             ...lazyBlocks,
+            {
+              type: "paragraph",
+              data: { text: "Broken image below: should fall back to the \"Select an Image\" button" },
+            },
+            {
+              type: "image",
+              data: {
+                file: { url: "https://example.invalid/broken.jpg" },
+                caption: "broken image",
+              },
+            },
           ],
         },
 
diff --git a/src/ui.ts b/src/ui.ts
index 9f1292b..be95f4d 100644
--- a/src/ui.ts
+++ b/src/ui.ts
@@ -271,6 +271,16 @@ export default class Ui {
       }
     });
 
+    /**
+     * If a lazy image fails to load, leave the preloader and show the empty state,
+     * so the image can be selected again (same as a failed non-lazy image)
+     */
+    if (attributes.loading === 'lazy') {
+      this.nodes.imageEl.addEventListener('error', () => {
+        this.toggleStatus(UiState.Empty);
+      });
+    }
+
     this.nodes.imageContainer.appendChild(this.nodes.imageEl);
   }