or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

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

tessl/npm-editorjs--image

Image Tool for Editor.js that enables users to add, configure, and manipulate images within Editor.js documents through multiple input methods including file uploads, URL pasting, drag-and-drop, and clipboard operations.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@editorjs/image@2.10.x

To install, run

npx @tessl/cli install tessl/npm-editorjs--image@2.10.0

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;
}