or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

commands.mdcore-functionality.mdimage-captions.mdimage-insertion.mdimage-resizing.mdimage-styling.mdimage-text-alternative.mdimage-upload.mdindex.mdutility-functions.md
tile.json

tessl/npm-ckeditor--ckeditor5-image

Comprehensive image handling functionality for CKEditor 5 rich text editor.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@ckeditor/ckeditor5-image@46.0.x

To install, run

npx @tessl/cli install tessl/npm-ckeditor--ckeditor5-image@46.0.0

index.mddocs/

CKEditor 5 Image

CKEditor 5 Image provides comprehensive image handling functionality for the CKEditor 5 rich text editor. It enables users to insert, upload, resize, style, and manage images within their editor content with support for drag-and-drop, responsive layouts, captions, alt text, and various display styles.

Package Information

  • Package Name: @ckeditor/ckeditor5-image
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ckeditor/ckeditor5-image

Overview

CKEditor 5 Image provides comprehensive image handling functionality for the CKEditor 5 rich text editor. It enables users to insert, upload, resize, style, and manage images within their editor content with support for drag-and-drop, responsive layouts, captions, alt text, and various display styles.

Key Features

  • Multiple insertion methods (upload, URL, drag-and-drop)
  • Interactive resizing with drag handles and preset options
  • Comprehensive styling system with alignment and custom styles
  • Accessibility support with alt text editing
  • Caption functionality for descriptive text
  • Block and inline image types
  • Progress tracking for uploads
  • Integration with various upload adapters

Core Imports

import { 
  Image, 
  ImageUpload, 
  ImageResize, 
  ImageStyle, 
  ImageToolbar,
  ImageUtils 
} from '@ckeditor/ckeditor5-image';

For CommonJS:

const { 
  Image, 
  ImageUpload, 
  ImageResize, 
  ImageStyle, 
  ImageToolbar,
  ImageUtils 
} = require('@ckeditor/ckeditor5-image');

Basic Usage

import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';
import { Image, ImageUpload, ImageResize, ImageStyle, ImageToolbar } from '@ckeditor/ckeditor5-image';

ClassicEditor
  .create(document.querySelector('#editor'), {
    plugins: [Image, ImageUpload, ImageResize, ImageStyle, ImageToolbar],
    toolbar: ['imageUpload'],
    image: {
      resizeOptions: [
        {
          name: 'resizeImage:original',
          value: null,
          icon: 'original'
        },
        {
          name: 'resizeImage:50',
          value: '50',
          icon: 'medium'
        }
      ],
      toolbar: ['imageTextAlternative', 'toggleImageCaption', 'imageStyle:inline', 'imageStyle:block']
    }
  })
  .then(editor => {
    console.log('Editor was initialized', editor);
  });

Architecture

CKEditor 5 Image is built around a modular plugin architecture with these key components:

  • Core Plugins: Main image functionality (Image, ImageBlock, ImageInline) handling both block and inline image types
  • Feature Plugins: Specialized capabilities like upload, resize, styling, captions, and alt text
  • Command System: Editor commands for all image operations (InsertImageCommand, ResizeImageCommand, etc.)
  • Configuration System: Type-safe configuration interfaces for customizing image behavior
  • Utility System: Helper functions and classes for image manipulation and detection
  • UI Components: Forms, buttons, and toolbars for user interaction

Capabilities

Core Image Functionality

Essential image plugins providing base image support with block and inline image types, automatic type detection, and widget integration.

class Image {
  static pluginName: 'Image';
  static requires: [ImageBlock, ImageInline];
  static isOfficialPlugin: true;
}

class ImageBlock {
  static pluginName: 'ImageBlock';
  static requires: [ImageBlockEditing, Widget, ImageTextAlternative, ImageInsertUI];
  static isOfficialPlugin: true;
}

class ImageInline {
  static pluginName: 'ImageInline';
  static requires: [ImageInlineEditing, Widget, ImageTextAlternative, ImageInsertUI];
  static isOfficialPlugin: true;
}

Core Functionality

Image Upload

Upload functionality supporting file selection, drag-and-drop, progress tracking, and integration with various upload adapters.

class ImageUpload {
  static pluginName: 'ImageUpload';
  static requires: [ImageUploadEditing, ImageUploadUI, ImageUploadProgress];
  static isOfficialPlugin: true;
}

interface ImageUploadConfig {
  types: Array<string>; // Default: ['jpeg', 'png', 'gif', 'bmp', 'webp', 'tiff']
}

Image Upload

Image Insertion

Comprehensive image insertion with multiple methods including upload, URL input, and extensible integration system.

class ImageInsert {
  static pluginName: 'ImageInsert';
  static requires: [ImageUpload, ImageInsertViaUrl, ImageInsertUI];
  static isOfficialPlugin: true;
}

interface ImageInsertConfig {
  integrations?: Array<string>; // Default: ['upload', 'assetManager', 'url']
  type?: 'inline' | 'block' | 'auto'; // Default: 'block'
}

Image Insertion

Image Resizing

Interactive image resizing with drag handles, preset size buttons, and custom size input with support for pixels and percentages.

class ImageResize {
  static pluginName: 'ImageResize';
  static requires: [ImageResizeEditing, ImageResizeHandles, ImageCustomResizeUI, ImageResizeButtons];
  static isOfficialPlugin: true;
}

interface ImageResizeOption {
  name: string;
  value: string | null; // null for original size
  icon?: string; // 'small', 'medium', 'large', 'original'
  label?: string;
}

Image Resizing

Image Styling

Comprehensive styling system with predefined styles (alignment, borders) and custom style definitions with CSS class mapping.

class ImageStyle {
  static pluginName: 'ImageStyle';
  static requires: [ImageStyleEditing, ImageStyleUI];
  static isOfficialPlugin: true;
}

interface ImageStyleConfig {
  options?: Array<string | ImageStyleOptionDefinition>;
}

interface ImageStyleOptionDefinition {
  name: string;
  isDefault?: boolean;
  icon: string;
  title: string;
  className?: string;
  modelElements: Array<string>; // ['imageBlock'], ['imageInline'], or both
}

Image Styling

Image Captions

Caption functionality allowing users to add, edit, and toggle descriptive text below images with full editor integration.

class ImageCaption {
  static pluginName: 'ImageCaption';
  static requires: [ImageCaptionEditing, ImageCaptionUI];
  static isOfficialPlugin: true;
}

Image Captions

Image Text Alternative

Alt text functionality for accessibility compliance with form-based editing and validation.

class ImageTextAlternative {
  static pluginName: 'ImageTextAlternative';
  static requires: [ImageTextAlternativeEditing, ImageTextAlternativeUI];
  static isOfficialPlugin: true;
}

Image Text Alternative

Utility Functions

Comprehensive utility system for image detection, manipulation, widget creation, and element conversion.

class ImageUtils {
  static pluginName: 'ImageUtils';
  static isOfficialPlugin: true;
  
  isImage(modelElement?: ModelElement | null): boolean;
  isInlineImage(modelElement?: ModelElement | null): boolean;
  isBlockImage(modelElement?: ModelElement | null): boolean;
  insertImage(attributes: object, selectable?: any, imageType?: string, options?: object): ModelElement | null;
  getClosestSelectedImageWidget(selection: any): ViewElement | null;
  getClosestSelectedImageElement(selection: any): ModelElement | null;
}

Utility Functions

Commands

Editor commands for programmatic image operations including insertion, resizing, styling, and source replacement.

class InsertImageCommand {
  execute(options: {
    source: string | Array<string | object>;
    imageType?: 'imageBlock' | 'imageInline';
    breakBlock?: boolean;
  }): void;
}

class ResizeImageCommand {
  execute(options: { width: string | null }): void;
  value: { width: string | null, height: string | null } | null;
}

Commands

Configuration

interface ImageConfig {
  insert?: ImageInsertConfig;
  resizeOptions?: Array<ImageResizeOption>;
  resizeUnit?: 'px' | '%'; // Default: '%'
  styles?: ImageStyleConfig;
  toolbar?: Array<string | ImageStyleDropdownDefinition>;
  upload?: ImageUploadConfig;
}

Types

interface ImageUploadCompleteEvent {
  name: 'uploadComplete';
}

interface ImageUploadCompleteData {
  imageElement: ModelElement;
}

interface ImageLoadedEvent {
  name: 'imageLoaded';
  args: [{ imageElement: ViewElement }];
}