or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcustomization.mdindex.mdui-management.mdupload.md
tile.json

index.mddocs/

@editorjs/image

@editorjs/image is a comprehensive Image Tool plugin for Editor.js that enables users to add, configure, and manipulate images within Editor.js documents. It supports multiple input methods including file uploads from devices, URL pasting, drag-and-drop functionality, and clipboard operations, along with advanced image customization features.

Package Information

  • Package Name: @editorjs/image
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @editorjs/image

Core Imports

import ImageTool from '@editorjs/image';

For CommonJS:

const ImageTool = require('@editorjs/image');

Basic Usage

import ImageTool from '@editorjs/image';
import EditorJS from '@editorjs/editorjs';

const editor = new EditorJS({
  tools: {
    image: {
      class: ImageTool,
      config: {
        endpoints: {
          byFile: 'http://localhost:8008/uploadFile',
          byUrl: 'http://localhost:8008/fetchUrl',
        }
      }
    }
  }
});

For CDN usage:

// Load from CDN
const ImageTool = window.ImageTool;

const editor = new EditorJS({
  tools: {
    image: {
      class: ImageTool,
      config: {
        endpoints: {
          byFile: '/api/upload',
          byUrl: '/api/upload-url'
        }
      }
    }
  }
});

Architecture

@editorjs/image is built around several core components:

  • ImageTool Class: Main tool implementation that integrates with Editor.js Block Tool interface
  • Upload System: Handles multiple upload methods (file selection, URL, drag-and-drop, clipboard paste)
  • UI Management: Manages visual states, preview loading, and image display
  • Tune System: Provides customization options (borders, backgrounds, stretching, captions)
  • Type Safety: Full TypeScript support with comprehensive type definitions
  • Paste Handling: Automatic detection and processing of pasted images from various sources

Capabilities

Core Tool Integration

Main ImageTool class that implements Editor.js Block Tool interface for seamless integration with the block editor.

export default class ImageTool implements BlockTool {
  constructor(options: ImageToolConstructorOptions);
  
  static get isReadOnlySupported(): boolean;
  static get toolbox(): ToolboxConfig;
  static get tunes(): Array<ActionConfig>;
  static get pasteConfig(): PasteConfig;
  
  render(): HTMLDivElement;
  validate(savedData: ImageToolData): boolean;
  save(): ImageToolData;
  renderSettings(): TunesMenuConfig;
  appendCallback(): void;
  onPaste(event: PasteEvent): Promise<void>;
}

type ImageToolConstructorOptions = BlockToolConstructorOptions<ImageToolData, ImageConfig>;

interface ToolboxConfig {
  icon: string;
  title: string;
}

interface TunesMenuConfig {
  icon: string;
  label: string;
  name: string;
  toggle?: boolean;
  isActive: boolean;
  onActivate: () => void;
}

Configuration and Setup

File Upload Operations

Comprehensive file upload system supporting device files, URLs, drag-and-drop, and clipboard paste operations with both default and custom upload handlers.

interface ImageConfig {
  endpoints?: {
    byFile?: string;
    byUrl?: string;
  };
  field?: string;
  types?: string;
  captionPlaceholder?: string;
  buttonContent?: string;
  additionalRequestData?: object;
  additionalRequestHeaders?: object;
  uploader?: {
    uploadByFile?: (file: Blob) => Promise<UploadResponseFormat>;
    uploadByUrl?: (url: string) => Promise<UploadResponseFormat>;
  };
  actions?: ActionConfig[];
  features?: FeaturesConfig;
}

interface UploadResponseFormat<AdditionalFileData = {}> {
  success: number;
  file: {
    url: string;
  } & AdditionalFileData;
}

File Upload Operations

Image Customization and Tunes

Visual customization system providing borders, backgrounds, stretching, and caption functionality with configurable feature toggles.

interface ActionConfig {
  name: string;
  icon: string;
  title: string;
  toggle?: boolean;
  action?: Function;
}

interface FeaturesConfig {
  background?: boolean;
  border?: boolean;
  caption?: boolean | 'optional';
  stretch?: boolean;
}

Customization and Tunes

UI Management System

Comprehensive UI management providing visual state control, preview handling, image display, and tune application with complete DOM manipulation capabilities.

class Ui {
  constructor(params: ConstructorParams);
  
  applyTune(tuneName: string, status: boolean): void;
  render(): HTMLElement;
  showPreloader(src: string): void;
  hidePreloader(): void;
  fillImage(url: string): void;
  fillCaption(text: string): void;
  toggleStatus(status: UiState): void;
  
  nodes: Nodes;
}

enum UiState {
  Empty = 'empty',
  Uploading = 'uploading',
  Filled = 'filled'
}

UI Management System

Core Types

interface ImageToolData<Actions = {}, AdditionalFileData = {}> {
  caption: string;
  withBorder: boolean;
  withBackground: boolean;
  stretched: boolean;
  file: {
    url: string;
  } & AdditionalFileData;
} & (Actions extends Record<string, boolean> ? Actions : {});

interface PasteConfig {
  tags: Array<{
    img: { src: boolean };
  }>;
  patterns: {
    image: RegExp;
  };
  files: {
    mimeTypes: string[];
  };
}

interface PasteEvent {
  type: 'tag' | 'pattern' | 'file';
  detail: HTMLPasteEventDetailExtended | PatternPasteEventDetail | FilePasteEventDetail;
}

interface UploadOptions {
  onPreview: (src: string) => void;
}

type ImageSetterParam = {
  url: string;
};

interface HTMLPasteEventDetailExtended extends HTMLPasteEventDetail {
  data: {
    src: string;
  } & HTMLElement;
}

interface PatternPasteEventDetail {
  data: string;
}

interface FilePasteEventDetail {
  file: File;
}

interface HTMLPasteEventDetail {
  data: HTMLElement;
}

interface BlockToolConstructorOptions<T = any, K = any> {
  data: T;
  config: K;
  api: API;
  readOnly: boolean;  
  block: BlockAPI;
}

interface BlockTool {
  render(): HTMLElement;
  save(): any;
  validate?(data: any): boolean;
  renderSettings?(): any;
  destroy?(): void;
}

interface BlockAPI {
  stretched: boolean;
}

interface API {
  i18n: {
    t(key: string): string;
  };
  notifier: {
    show(options: { message: string; style: string }): void;
  };
  styles: {
    block: string;
    loader: string;
    input: string;
    button: string;
  };
}

interface ConstructorParams {
  api: API;
  config: ImageConfig;
  onSelectFile: () => void;
  readOnly: boolean;
}

interface Nodes {
  wrapper: HTMLElement;
  imageContainer: HTMLElement;
  fileButton: HTMLElement;
  imageEl?: HTMLElement;
  imagePreloader: HTMLElement;
  caption: HTMLElement;
}