From 09c104fd6e5f1422e1c8274cb7913f81d3c40038 Mon Sep 17 00:00:00 2001
From: dependenthodor <madani.badaoui1995@gmail.com>
Date: Tue, 9 Sep 2025 17:11:24 +0100
Subject: [PATCH 1/4] chore: add alt tag

---
 dev/index.html     |  4 +++-
 src/index.css      | 48 ++++++++++++++++++++++++++++++++++++-
 src/index.ts       | 60 ++++++++++++++++++++++++++++++++++++++++++++++
 src/types/types.ts | 15 ++++++++++++
 src/ui.ts          | 45 ++++++++++++++++++++++++++++++++++
 5 files changed, 170 insertions(+), 2 deletions(-)

diff --git a/dev/index.html b/dev/index.html
index 2383256..16d3b94 100644
--- a/dev/index.html
+++ b/dev/index.html
@@ -9,7 +9,7 @@
     <div id="editorjs"></div>
     <script src="https://cdn.jsdelivr.net/npm/@editorjs/editorjs@latest"></script>
     <script type="module">
-      import ImageTool from "../src/index.ts";
+      import ImageTool from "../dist/image.mjs";
       const editor = new EditorJS({
         holder: "editorjs",
         data: {
@@ -26,6 +26,7 @@
                 withBackground: false,
                 stretched: false,
                 caption: "kimitsu no yayiba",
+                alt: "Picture of anime characters"
               },
             },
           ],
@@ -44,6 +45,7 @@
                 border: false,
                 background: false,
                 stretch: true,
+                alt: "optional",
               },
             },
           },
diff --git a/src/index.css b/src/index.css
index 55342ef..a6d8c34 100644
--- a/src/index.css
+++ b/src/index.css
@@ -70,6 +70,32 @@
     }
   }
 
+  &__alt {
+    visibility: hidden;
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    margin-bottom: 10px;
+
+    &[contentEditable="true"][data-placeholder]::before {
+      position: absolute !important;
+      content: attr(data-placeholder);
+      color: #707684;
+      font-weight: normal;
+      display: none;
+    }
+
+    &[contentEditable="true"][data-placeholder]:empty {
+      &::before {
+        display: block;
+      }
+
+      &:focus::before {
+        display: none;
+      }
+    }
+  }
+
   &--empty {
     ^&__image {
       display: none;
@@ -85,6 +111,10 @@
     ^&__caption {
       visibility: hidden !important;
     }
+
+    ^&__alt {
+      visibility: hidden !important;
+    }
   }
 
   .cdx-button {
@@ -163,7 +193,23 @@
       visibility: visible;
     }
 
-    padding-bottom: 50px
+    padding-bottom: 50px;
+  }
+
+  &--alt {
+    ^&__alt {
+      visibility: visible;
+    }
+
+    padding-bottom: 50px;
+  }
+
+  &--caption&--alt {
+    ^&__caption {
+      bottom: 30px;
+    }
+
+    padding-bottom: 80px;
   }
 }
 
diff --git a/src/index.ts b/src/index.ts
index 7700606..4b44373 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -82,6 +82,14 @@ export default class ImageTool implements BlockTool {
    */
   private isCaptionEnabled: boolean | null = null;
 
+  /**
+   * Alt text enabled state
+   * Null when user has not toggled the alt tune
+   * True when user has toggled the alt tune
+   * False when user has toggled the alt tune
+   */
+  private isAltEnabled: boolean | null = null;
+
   /**
    * @param tool - tool properties got from editor.js
    * @param tool.data - previously saved data
@@ -104,6 +112,7 @@ export default class ImageTool implements BlockTool {
       field: config.field,
       types: config.types,
       captionPlaceholder: this.api.i18n.t(config.captionPlaceholder ?? 'Caption'),
+      altPlaceholder: this.api.i18n.t(config.altPlaceholder ?? 'Alt text'),
       buttonContent: config.buttonContent,
       uploader: config.uploader,
       actions: config.actions,
@@ -140,6 +149,7 @@ export default class ImageTool implements BlockTool {
      */
     this._data = {
       caption: '',
+      alt: '',
       withBorder: false,
       withBackground: false,
       stretched: false,
@@ -204,6 +214,11 @@ export default class ImageTool implements BlockTool {
       this.ui.applyTune('caption', true);
     }
 
+    if (this.config.features?.alt === true || (this.config.features?.alt === 'optional' && this.data.alt)) {
+      this.isAltEnabled = true;
+      this.ui.applyTune('alt', true);
+    }
+
     return this.ui.render() as HTMLDivElement;
   }
 
@@ -221,8 +236,10 @@ export default class ImageTool implements BlockTool {
    */
   public save(): ImageToolData {
     const caption = this.ui.nodes.caption;
+    const alt = this.ui.nodes.alt;
 
     this._data.caption = caption.innerHTML;
+    this._data.alt = alt.innerHTML;
 
     return this.data;
   }
@@ -240,6 +257,7 @@ export default class ImageTool implements BlockTool {
       background: 'withBackground',
       stretch: 'stretched',
       caption: 'caption',
+      alt: 'alt',
     };
 
     if (this.config.features?.caption === 'optional') {
@@ -251,6 +269,15 @@ export default class ImageTool implements BlockTool {
       });
     }
 
+    if (this.config.features?.alt === 'optional') {
+      tunes.push({
+        name: 'alt',
+        icon: IconText,
+        title: 'With alt text',
+        toggle: true,
+      });
+    }
+
     const availableTunes = tunes.filter((tune) => {
       const featureKey = Object.keys(featureTuneMap).find(key => featureTuneMap[key] === tune.name);
 
@@ -258,6 +285,10 @@ export default class ImageTool implements BlockTool {
         return this.config.features?.caption !== false;
       }
 
+      if (featureKey === 'alt') {
+        return this.config.features?.alt !== false;
+      }
+
       return featureKey == null || this.config.features?.[featureKey as keyof FeaturesConfig] !== false;
     });
 
@@ -272,6 +303,10 @@ export default class ImageTool implements BlockTool {
         currentState = this.isCaptionEnabled ?? currentState;
       }
 
+      if (tune.name === 'alt') {
+        currentState = this.isAltEnabled ?? currentState;
+      }
+
       return currentState;
     };
 
@@ -299,6 +334,15 @@ export default class ImageTool implements BlockTool {
           newState = this.isCaptionEnabled;
         }
 
+        /**
+         * For the alt tune, we can't rely on the this._data
+         * because it can be manualy toggled by user
+         */
+        if (tune.name === 'alt') {
+          this.isAltEnabled = !(this.isAltEnabled ?? false);
+          newState = this.isAltEnabled;
+        }
+
         this.tuneToggled(tune.name as keyof ImageToolData, newState);
       },
     }));
@@ -396,6 +440,9 @@ export default class ImageTool implements BlockTool {
     this._data.caption = data.caption || '';
     this.ui.fillCaption(this._data.caption);
 
+    this._data.alt = data.alt || '';
+    this.ui.fillAlt(this._data.alt);
+
     ImageTool.tunes.forEach(({ name: tune }) => {
       const value = typeof data[tune as keyof ImageToolData] !== 'undefined' ? data[tune as keyof ImageToolData] === true || data[tune as keyof ImageToolData] === 'true' : false;
 
@@ -407,6 +454,12 @@ export default class ImageTool implements BlockTool {
     } else if (this.config.features?.caption === true) {
       this.setTune('caption', true);
     }
+
+    if (data.alt) {
+      this.setTune('alt', true);
+    } else if (this.config.features?.alt === true) {
+      this.setTune('alt', true);
+    }
   }
 
   /**
@@ -467,6 +520,13 @@ export default class ImageTool implements BlockTool {
         this._data.caption = '';
         this.ui.fillCaption('');
       }
+    } else if (tuneName === 'alt') {
+      this.ui.applyTune(tuneName, state);
+
+      if (state == false) {
+        this._data.alt = '';
+        this.ui.fillAlt('');
+      }
     } else {
       /**
        * Inverse tune state
diff --git a/src/types/types.ts b/src/types/types.ts
index 3de5505..c886c3d 100644
--- a/src/types/types.ts
+++ b/src/types/types.ts
@@ -73,6 +73,11 @@ export type ImageToolData<Actions = {}, AdditionalFileData = {}> = {
    */
   caption: string;
 
+  /**
+   * Alt text for the image.
+   */
+  alt: string;
+
   /**
    * Flag indicating whether the image has a border.
    */
@@ -117,6 +122,11 @@ export type FeaturesConfig = {
    * Can be set to 'optional' to allow users to toggle via block tunes.
    */
   caption?: boolean | 'optional';
+  /**
+   * Flag to enable/disable alt text.
+   * Can be set to 'optional' to allow users to toggle via block tunes.
+   */
+  alt?: boolean | 'optional';
   /**
    * Flag to enable/disable tune - stretched
    */
@@ -159,6 +169,11 @@ export interface ImageConfig {
    */
   captionPlaceholder?: string;
 
+  /**
+   * Placeholder text for the alt text field.
+   */
+  altPlaceholder?: string;
+
   /**
    * Additional data to send with requests.
    */
diff --git a/src/ui.ts b/src/ui.ts
index f66afa0..5fc6830 100644
--- a/src/ui.ts
+++ b/src/ui.ts
@@ -56,6 +56,11 @@ interface Nodes {
    * Caption element for the image.
    */
   caption: HTMLElement;
+
+  /**
+   * Alt text element for the image.
+   */
+  alt: HTMLElement;
 }
 
 /**
@@ -133,6 +138,9 @@ export default class Ui {
       caption: make('div', [this.CSS.input, this.CSS.caption], {
         contentEditable: !this.readOnly,
       }),
+      alt: make('div', [this.CSS.input, this.CSS.alt], {
+        contentEditable: !this.readOnly,
+      }),
     };
 
     /**
@@ -142,13 +150,22 @@ export default class Ui {
      *      <image-preloader />
      *    </image-container>
      *    <caption />
+     *    <alt />
      *    <select-file-button />
      *  </wrapper>
      */
     this.nodes.caption.dataset.placeholder = this.config.captionPlaceholder;
+    this.nodes.alt.dataset.placeholder = this.config.altPlaceholder || this.api.i18n.t('Alt text');
+    
+    // Add event listener to update alt attribute when alt text changes
+    this.nodes.alt.addEventListener('input', () => {
+      this.updateImageAlt(this.nodes.alt.innerHTML);
+    });
+    
     this.nodes.imageContainer.appendChild(this.nodes.imagePreloader);
     this.nodes.wrapper.appendChild(this.nodes.imageContainer);
     this.nodes.wrapper.appendChild(this.nodes.caption);
+    this.nodes.wrapper.appendChild(this.nodes.alt);
     this.nodes.wrapper.appendChild(this.nodes.fileButton);
   }
 
@@ -202,6 +219,11 @@ export default class Ui {
       src: url,
     };
 
+    // Add alt attribute for IMG tags
+    if (tag === 'IMG') {
+      attributes.alt = this.nodes.alt.innerHTML || '';
+    }
+
     /**
      * We use eventName variable because IMG and VIDEO tags have different event to be called on source load
      * - IMG: load
@@ -259,6 +281,28 @@ export default class Ui {
     }
   }
 
+  /**
+   * Shows alt text input
+   * @param text - alt text content
+   */
+  public fillAlt(text: string): void {
+    if (this.nodes.alt !== undefined) {
+      this.nodes.alt.innerHTML = text;
+      // Update the alt attribute on the image element if it exists
+      this.updateImageAlt(text);
+    }
+  }
+
+  /**
+   * Updates the alt attribute on the image element
+   * @param altText - alt text to set
+   */
+  public updateImageAlt(altText: string): void {
+    if (this.nodes.imageEl && this.nodes.imageEl.tagName === 'IMG') {
+      this.nodes.imageEl.setAttribute('alt', altText);
+    }
+  }
+
   /**
    * Changes UI status
    * @param status - see {@link Ui.status} constants
@@ -291,6 +335,7 @@ export default class Ui {
       imagePreloader: 'image-tool__image-preloader',
       imageEl: 'image-tool__image-picture',
       caption: 'image-tool__caption',
+      alt: 'image-tool__alt',
     };
   };
 

From 309bd4327a1ad504fe8c90a4f3334f68083d22ba Mon Sep 17 00:00:00 2001
From: dependenthodor <madani.badaoui1995@gmail.com>
Date: Wed, 10 Sep 2025 19:04:30 +0100
Subject: [PATCH 2/4] fix: fix related to the use of i18n, alt positioning with
 caption

---
 dev/index.html |  2 +-
 src/index.css  | 33 ++++++---------------------------
 src/index.ts   | 17 +++++++----------
 src/ui.ts      |  2 +-
 4 files changed, 15 insertions(+), 39 deletions(-)

diff --git a/dev/index.html b/dev/index.html
index 16d3b94..d093b7e 100644
--- a/dev/index.html
+++ b/dev/index.html
@@ -9,7 +9,7 @@
     <div id="editorjs"></div>
     <script src="https://cdn.jsdelivr.net/npm/@editorjs/editorjs@latest"></script>
     <script type="module">
-      import ImageTool from "../dist/image.mjs";
+      import ImageTool from "../src/index.ts";
       const editor = new EditorJS({
         holder: "editorjs",
         data: {
diff --git a/src/index.css b/src/index.css
index a6d8c34..41b78a2 100644
--- a/src/index.css
+++ b/src/index.css
@@ -44,32 +44,7 @@
     }
   }
 
-  &__caption {
-    visibility: hidden;
-    position: absolute;
-    bottom: 0;
-    left: 0;
-    margin-bottom: 10px;
-
-    &[contentEditable="true"][data-placeholder]::before {
-      position: absolute !important;
-      content: attr(data-placeholder);
-      color: #707684;
-      font-weight: normal;
-      display: none;
-    }
-
-    &[contentEditable="true"][data-placeholder]:empty {
-      &::before {
-        display: block;
-      }
-
-      &:focus::before {
-        display: none;
-      }
-    }
-  }
-
+  &__caption,
   &__alt {
     visibility: hidden;
     position: absolute;
@@ -206,7 +181,11 @@
 
   &--caption&--alt {
     ^&__caption {
-      bottom: 30px;
+      bottom: 40px;
+    }
+
+    ^&__alt {
+      bottom: 0px;
     }
 
     padding-bottom: 80px;
diff --git a/src/index.ts b/src/index.ts
index 4b44373..d7ebfdd 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -84,11 +84,8 @@ export default class ImageTool implements BlockTool {
 
   /**
    * Alt text enabled state
-   * Null when user has not toggled the alt tune
-   * True when user has toggled the alt tune
-   * False when user has toggled the alt tune
    */
-  private isAltEnabled: boolean | null = null;
+  private isAltEnabled: boolean = false;
 
   /**
    * @param tool - tool properties got from editor.js
@@ -262,18 +259,18 @@ export default class ImageTool implements BlockTool {
 
     if (this.config.features?.caption === 'optional') {
       tunes.push({
-        name: 'caption',
+        name: this.api.i18n.t('caption'),
         icon: IconText,
-        title: 'With caption',
+        title: this.api.i18n.t('With caption'),
         toggle: true,
       });
     }
 
     if (this.config.features?.alt === 'optional') {
       tunes.push({
-        name: 'alt',
+        name: this.api.i18n.t('alt'),
         icon: IconText,
-        title: 'With alt text',
+        title: this.api.i18n.t('With alt text'),
         toggle: true,
       });
     }
@@ -304,7 +301,7 @@ export default class ImageTool implements BlockTool {
       }
 
       if (tune.name === 'alt') {
-        currentState = this.isAltEnabled ?? currentState;
+        currentState = this.isAltEnabled;
       }
 
       return currentState;
@@ -339,7 +336,7 @@ export default class ImageTool implements BlockTool {
          * because it can be manualy toggled by user
          */
         if (tune.name === 'alt') {
-          this.isAltEnabled = !(this.isAltEnabled ?? false);
+          this.isAltEnabled = !this.isAltEnabled;
           newState = this.isAltEnabled;
         }
 
diff --git a/src/ui.ts b/src/ui.ts
index 5fc6830..fbb0acb 100644
--- a/src/ui.ts
+++ b/src/ui.ts
@@ -221,7 +221,7 @@ export default class Ui {
 
     // Add alt attribute for IMG tags
     if (tag === 'IMG') {
-      attributes.alt = this.nodes.alt.innerHTML || '';
+      attributes.alt = this.nodes.alt.textContent || '';
     }
 
     /**

From ebe967a0afc6c0526fbe7429c68b8f7effdbf8b3 Mon Sep 17 00:00:00 2001
From: dependenthodor <madani.badaoui1995@gmail.com>
Date: Thu, 11 Sep 2025 16:13:28 +0100
Subject: [PATCH 3/4] update: remove i18n for name value

---
 src/index.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/index.ts b/src/index.ts
index d7ebfdd..657cbfd 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -259,7 +259,7 @@ export default class ImageTool implements BlockTool {
 
     if (this.config.features?.caption === 'optional') {
       tunes.push({
-        name: this.api.i18n.t('caption'),
+        name: 'caption',
         icon: IconText,
         title: this.api.i18n.t('With caption'),
         toggle: true,
@@ -268,7 +268,7 @@ export default class ImageTool implements BlockTool {
 
     if (this.config.features?.alt === 'optional') {
       tunes.push({
-        name: this.api.i18n.t('alt'),
+        name: 'alt',
         icon: IconText,
         title: this.api.i18n.t('With alt text'),
         toggle: true,

From 3c93262fbbfe321509699cdf450aa7672236d249 Mon Sep 17 00:00:00 2001
From: dependenthodor <madani.badaoui1995@gmail.com>
Date: Fri, 12 Sep 2025 14:48:33 +0100
Subject: [PATCH 4/4] update: patch version incremeneted

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 954edf8..456558b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@editorjs/image",
-  "version": "2.10.3",
+  "version": "2.10.4",
   "keywords": [
     "codex editor",
     "image",