@ckeditor/ckeditor5-image

@ckeditor/ckeditor5-image

Version 43.1.0
Published 1 day ago
3.15 MB
11 dependencies
GPL-2.0-or-later license

Install

npm i @ckeditor/ckeditor5-image

yarn add @ckeditor/ckeditor5-image

pnpm add @ckeditor/ckeditor5-image

Overview

Image feature for CKEditor 5.

Index

Classes

class AutoImage

class AutoImage extends Plugin {}

The auto-image plugin. It recognizes image links in the pasted content and embeds them shortly after they are injected into the document.

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any, typeof ImageUtils, any, any];

method init

init: () => void;

class Image

class Image extends Plugin {}

The image plugin.
For a detailed overview, check the documentation.
This is a "glue" plugin which loads the following plugins:
* , * ,
Usually, it is used in conjunction with other plugins from this package. See the for more information.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageBlock, typeof ImageInline];

class ImageBlock

class ImageBlock extends Plugin {}

The image block plugin.
This is a "glue" plugin which loads the following plugins:
* , * .
Usually, it is used in conjunction with other plugins from this package. See the for more information.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ImageBlockEditing,
    any,
    typeof ImageTextAlternative,
    typeof ImageInsertUI
];

class ImageBlockEditing

class ImageBlockEditing extends Plugin {}

The image block plugin.
It registers:
* <imageBlock> as a block element in the document schema, and allows alt, src and srcset attributes. * converters for editing and data pipelines., * command that converts inline images into block images.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ImageEditing,
    typeof ImageSizeAttributes,
    typeof ImageUtils,
    typeof ImagePlaceholder,
    any
];

method init

init: () => void;

class ImageCaption

class ImageCaption extends Plugin {}

The image caption plugin.
For a detailed overview, check the documentation.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ImageCaptionEditing,
    typeof ImageCaptionUI
];

class ImageCaptionEditing

class ImageCaptionEditing extends Plugin {}

The image caption engine plugin. It is responsible for:
* registering converters for the caption element, * registering converters for the caption model attribute, * registering the command.

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageUtils, typeof ImageCaptionUtils];

method init

init: () => void;

class ImageCaptionUI

class ImageCaptionUI extends Plugin {}

The image caption UI plugin. It introduces the 'toggleImageCaption' UI button.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageCaptionUtils];

method init

init: () => void;

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageUtils];

method getCaptionFromImageModelElement

getCaptionFromImageModelElement: (imageModelElement: Element) => Element | null;

Returns the caption model element from a given image element. Returns null if no caption is found.

method getCaptionFromModelSelection

getCaptionFromModelSelection: (
    selection: Selection | DocumentSelection
) => Element | null;

Returns the caption model element for a model selection. Returns null if the selection has no caption element ancestor.

method matchImageCaptionViewElement

matchImageCaptionViewElement: (element: ViewElement) => Match | null;

pattern. Checks if a given element is a <figcaption> element that is placed inside the image <figure> element.
Returns
Returns the object accepted by or null if the element cannot be matched.

class ImageCustomResizeUI

class ImageCustomResizeUI extends Plugin {}

The custom resize image UI plugin.
The plugin uses the .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any];

method destroy

destroy: () => void;

class ImageEditing

class ImageEditing extends Plugin {}

The image engine plugin. This module loads common code shared between and plugins.
This plugin registers the command.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageUtils];

method init

init: () => void;

class ImageInline

class ImageInline extends Plugin {}

The image inline plugin.
This is a "glue" plugin which loads the following plugins:
* , * .
Usually, it is used in conjunction with other plugins from this package. See the for more information.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ImageInlineEditing,
    any,
    typeof ImageTextAlternative,
    typeof ImageInsertUI
];

class ImageInsert

class ImageInsert extends Plugin {}

The image insert plugin.
For a detailed overview, check the and documentation.
This plugin does not do anything directly, but it loads a set of specific plugins to enable image uploading or inserting via implemented integrations:
* *

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ImageUpload,
    typeof ImageInsertViaUrl,
    typeof ImageInsertUI
];

class ImageInsertUI

class ImageInsertUI extends Plugin {}

The image insert dropdown plugin.
For a detailed overview, check the and documentation.
Adds the 'insertImage' dropdown to the and also the imageInsert dropdown as an alias for backward compatibility.
Adds the 'menuBar:insertImage' sub-menu to the , which is by default added to the 'Insert' menu.

constructor

constructor(editor: Editor);

property dropdownView

dropdownView?: DropdownView;

The dropdown view responsible for displaying the image insert UI.

property isImageSelected

isImageSelected: boolean;

Observable property used to alter labels while some image is selected and when it is not.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageUtils];

method init

init: () => void;

method registerIntegration

registerIntegration: ({
    name,
    observable,
    buttonViewCreator,
    formViewCreator,
    menuBarButtonViewCreator,
    requiresForm,
}: {
    name: string;
    observable:
        | (Observable & { isEnabled: boolean })
        | (() => Observable & { isEnabled: boolean });
    buttonViewCreator: (isOnlyOne: boolean) => ButtonView;
    formViewCreator: (isOnlyOne: boolean) => FocusableView;
    menuBarButtonViewCreator: (
        isOnlyOne: boolean
    ) => MenuBarMenuListItemButtonView;
    requiresForm?: boolean;
}) => void;

Registers the insert image dropdown integration.

class ImageInsertViaUrl

class ImageInsertViaUrl extends Plugin {}

The image insert via URL plugin.
For a detailed overview, check the documentation.
This plugin does not do anything directly, but it loads a set of specific plugins to enable image inserting via implemented integrations:
* ,

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ImageInsertViaUrlUI,
    typeof ImageInsertUI
];

class ImageResize

class ImageResize extends Plugin {}

The image resize plugin.
It adds a possibility to resize each image using handles.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ImageResizeEditing,
    typeof ImageResizeHandles,
    typeof ImageCustomResizeUI,
    typeof ImageResizeButtons
];

class ImageResizeButtons

class ImageResizeButtons extends Plugin {}

The image resize buttons plugin.
It adds a possibility to resize images using the toolbar dropdown or individual buttons, depending on the plugin configuration.

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageResizeEditing];

method init

init: () => void;

class ImageResizeEditing

class ImageResizeEditing extends Plugin {}

The image resize editing feature.
It adds the ability to resize each image using handles or manually by buttons.

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageUtils];

method afterInit

afterInit: () => void;

method init

init: () => void;

class ImageResizeHandles

class ImageResizeHandles extends Plugin {}

The image resize by handles feature.
It adds the ability to resize each image using handles or manually by buttons.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any, typeof ImageUtils];

method init

init: () => void;

class ImageSizeAttributes

class ImageSizeAttributes extends Plugin {}

This plugin enables width and height attributes in inline and block image elements.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageUtils];

method afterInit

afterInit: () => void;

class ImageStyle

class ImageStyle extends Plugin {}

The image style plugin.
For a detailed overview of the image styles feature, check the .
This is a "glue" plugin which loads the following plugins: * , *
It provides a default configuration, which can be extended or overwritten. Read more about the .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ImageStyleEditing,
    typeof ImageStyleUI
];

class ImageStyleCommand

class ImageStyleCommand extends Command {}

The image style command. It is used to apply to a selected image.
**Note**: Executing this command may change the image model element if the desired style requires an image of a different type. See to learn more.

constructor

constructor(editor: Editor, styles: ImageStyleOptionDefinition[]);

Creates an instance of the image style command. When executed, the command applies one of to the currently selected image.
Parameter editor
The editor instance.
Parameter styles
The style options that this command supports.

method execute

execute: (options?: { value?: string; setImageSizes?: boolean }) => void;

Executes the command and applies the style to the currently selected image:
editor.execute( 'imageStyle', { value: 'side' } );
**Note**: Executing this command may change the image model element if the desired style requires an image of a different type. Learn more about configuration for the style option.
Parameter
options.value The name of the style (as configured in ).
Parameter
options.setImageSizes Specifies whether the image width and height attributes should be set automatically. The default is true. execute

method refresh

refresh: () => void;

method shouldConvertImageType

shouldConvertImageType: (
    requestedStyle: string,
    imageElement: Element
) => boolean;

Returns true if requested style change would trigger the image type change.
Parameter requestedStyle
The name of the style (as configured in ).
Parameter imageElement
The image model element.

class ImageStyleEditing

class ImageStyleEditing extends Plugin {}

The image style engine plugin. It sets the default configuration, creates converters and registers .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageUtils];

method init

init: () => void;

class ImageStyleUI

class ImageStyleUI extends Plugin {}

The image style UI plugin.
It registers buttons corresponding to the configuration. It also registers the and the custom drop-downs defined by the developer in the configuration.

property localizedDefaultStylesTitles

readonly localizedDefaultStylesTitles: Record<string, string>;

Returns the default localized style titles provided by the plugin.
The following localized titles corresponding with are available:
* 'Wrap text', * 'Break text', * 'In line', * 'Full size image', * 'Side image', * 'Left aligned image', * 'Centered image', * 'Right aligned image'

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageStyleEditing];

method init

init: () => void;

class ImageTextAlternative

class ImageTextAlternative extends Plugin {}

The image text alternative plugin.
For a detailed overview, check the documentation.
This is a "glue" plugin which loads the and plugins.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ImageTextAlternativeEditing,
    typeof ImageTextAlternativeUI
];

class ImageTextAlternativeCommand

class ImageTextAlternativeCommand extends Command {}

The image text alternative command. It is used to change the alt attribute of <imageBlock> and <imageInline> model elements.

property value

value: string | false;

The command value: false if there is no alt attribute, otherwise the value of the alt attribute.
Modifiers
- @readonly

method execute

execute: (options: { newValue: string }) => void;

Executes the command.
execute
Parameter options
Parameter
options.newValue The new value of the alt attribute to set.

method refresh

refresh: () => void;

class ImageTextAlternativeEditing

class ImageTextAlternativeEditing extends Plugin {}

The image text alternative editing plugin.
Registers the 'imageTextAlternative' command.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageUtils];

method init

init: () => void;

class ImageTextAlternativeUI

class ImageTextAlternativeUI extends Plugin {}

The image text alternative UI plugin.
The plugin uses the .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any];

method destroy

destroy: () => void;

method init

init: () => void;

class ImageToolbar

class ImageToolbar extends Plugin {}

The image toolbar plugin. It creates and manages the image toolbar (the toolbar displayed when an image is selected).
For an overview, check the documentation.
Instances of toolbar components (e.g. buttons) are created using the editor's based on the .
The toolbar uses the .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any, typeof ImageUtils];

method afterInit

afterInit: () => void;

class ImageTypeCommand

class ImageTypeCommand extends Command {}

The image type command. It changes the type of a selected image, depending on the configuration.

constructor

constructor(editor: Editor, modelElementName: 'imageBlock' | 'imageInline');

Parameter modelElementName
Model element name the command converts to.

method execute

execute: (options?: {
    setImageSizes?: boolean;
}) => { oldElement: Element; newElement: Element } | null;

Executes the command and changes the type of a selected image.
execute
Parameter
options.setImageSizes Specifies whether the image width and height attributes should be set automatically. The default is true.
Returns
An object containing references to old and new model image elements (for before and after the change) so external integrations can hook into the decorated execute event and handle this change. null if the type change failed.

method refresh

refresh: () => void;

class ImageUpload

class ImageUpload extends Plugin {}

The image upload plugin.
For a detailed overview, check the documentation.
This plugin does not do anything directly, but it loads a set of specific plugins to enable image uploading:
* , * , * .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ImageUploadEditing,
    typeof ImageUploadUI,
    typeof ImageUploadProgress
];

class ImageUploadEditing

class ImageUploadEditing extends Plugin {}

The editing part of the image upload feature. It registers the 'uploadImage' command and the imageUpload command as an aliased name.
When an image is uploaded, it fires the event that allows adding custom attributes to the .

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any, any, any, typeof ImageUtils];

method afterInit

afterInit: () => void;

method init

init: () => void;

class ImageUploadProgress

class ImageUploadProgress extends Plugin {}

The image upload progress plugin. It shows a placeholder when the image is read from the disk and a progress bar while the image is uploading.

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

method init

init: () => void;

class ImageUploadUI

class ImageUploadUI extends Plugin {}

The image upload button plugin.
For a detailed overview, check the documentation.
Adds the 'uploadImage' button to the and also the imageUpload button as an alias for backward compatibility.
Adds the 'menuBar:uploadImage' menu button to the .
It also integrates with the insertImage toolbar component and menuBar:insertImage menu component, which are the default components through which image upload is available.

property pluginName

static readonly pluginName: string;

method init

init: () => void;

property pluginName

static readonly pluginName: string;

method destroy

destroy: () => void;

method findViewImgElement

findViewImgElement: (figureView: ViewElement) => ViewElement | undefined;

Get the view <img> from another view element, e.g. a widget (<figure class="image">), a link (<a>).
The <img> can be located deep in other elements, so this helper performs a deep tree search.

method getClosestSelectedImageElement

getClosestSelectedImageElement: (
    selection: Selection | DocumentSelection
) => Element | null;

Returns a image model element if one is selected or is among the selection's ancestors.

method getClosestSelectedImageWidget

getClosestSelectedImageWidget: (
    selection: ViewSelection | ViewDocumentSelection
) => ViewElement | null;

Returns an image widget editing view element if one is selected or is among the selection's ancestors.

method getImageWidgetFromImageView

getImageWidgetFromImageView: (
    imageView: ViewElement
) => ViewContainerElement | null;

Returns an image widget editing view based on the passed image view.

method insertImage

insertImage: (
    attributes?: Record<string, unknown>,
    selectable?: Selection | Position | null,
    imageType?: 'imageBlock' | 'imageInline' | null,
    options?: { setImageSizes?: boolean }
) => Element | null;

Handles inserting single file. This method unifies image insertion using method.
const imageUtils = editor.plugins.get( 'ImageUtils' ); imageUtils.insertImage( { src: 'path/to/image.jpg' } );
Parameter attributes
Attributes of the inserted image. This method filters out the attributes which are disallowed by the .
Parameter selectable
Place to insert the image. If not specified, the logic will be applied for the block images and model.document.selection for the inline images.
**Note**: If selectable is passed, this helper will not be able to set selection attributes (such as linkHref) and apply them to the new image. In this case, make sure all selection attributes are passed in attributes.
Parameter imageType
Image type of inserted image. If not specified, it will be determined automatically depending of editor config or place of the insertion.
Parameter
options.setImageSizes Specifies whether the image width and height attributes should be set automatically. The default is true. The inserted model image element.

method isBlockImage

isBlockImage: (modelElement?: Element | null) => boolean;

Checks if the provided model element is an image.

method isBlockImageView

isBlockImageView: (element?: ViewElement | null) => boolean;

Checks if the provided view element represents a block image.
Also, see .

method isImage

isImage: (modelElement?: Element | null) => modelElement is any;

Checks if the provided model element is an image or imageInline.

method isImageWidget

protected isImageWidget: (viewElement: ViewElement) => boolean;

Checks if a given view element is an image widget.

method isInlineImage

isInlineImage: (modelElement?: Element | null) => boolean;

Checks if the provided model element is an imageInline.

method isInlineImageView

isInlineImageView: (element?: ViewElement | null) => boolean;

Checks if the provided view element represents an inline image.
Also, see .

method setImageNaturalSizeAttributes

setImageNaturalSizeAttributes: (imageElement: Element) => void;

Reads original image sizes and sets them as width and height.
The src attribute may not be available if the user is using an upload adapter. In such a case, this method is called again after the upload process is complete and the src attribute is available.

method toImageWidget

toImageWidget: (
    viewElement: ViewElement,
    writer: DowncastWriter,
    label: string
) => ViewElement;

Converts a given to an image widget: * Adds a allowing to recognize the image widget element. * Calls the function with the proper element's label creator.
Parameter writer
An instance of the view writer.
Parameter label
The element's label. It will be concatenated with the image alt attribute if one is present.

class InsertImageCommand

class InsertImageCommand extends Command {}

Insert image command.
The command is registered by the plugin as insertImage and it is also available via aliased imageInsert name.
In order to insert an image at the current selection position (according to the algorithm), execute the command and specify the image source:
editor.execute( 'insertImage', { source: 'http://url.to.the/image' } );
It is also possible to insert multiple images at once:
editor.execute( 'insertImage', { source: [ 'path/to/image.jpg', 'path/to/other-image.jpg' ] } );
If you want to take the full control over the process, you can specify individual model attributes:
editor.execute( 'insertImage', { source: [ { src: 'path/to/image.jpg', alt: 'First alt text' }, { src: 'path/to/other-image.jpg', alt: 'Second alt text', customAttribute: 'My attribute value' } ] } );

constructor

constructor(editor: Editor);

method execute

execute: (options: {
    source: ArrayOrItem<string | Record<string, unknown>>;
}) => void;

Executes the command.
execute
Parameter options
Options for the executed command.
Parameter
options.source The image source or an array of image sources to insert. See the documentation of the command to learn more about accepted formats.

method refresh

refresh: () => void;

class PictureEditing

class PictureEditing extends Plugin {}

This plugin enables the [<picture>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture) element support in the editor.

* It enables the sources model attribute on imageBlock and imageInline model elements (brought by and , respectively). * It translates the sources model element to the view (also: data) structure that may look as follows:

<p>Inline image using picture:
	<picture>
		<source media="(min-width: 800px)" srcset="image-large.webp" type="image/webp">
		<source media="(max-width: 800px)" srcset="image-small.webp" type="image/webp">
		<!-- Other sources as specified in the "sources" model attribute... -->
		<img src="image.png" alt="An image using picture" />
	</picture>
</p>

<p>Block image using picture:</p>
<figure class="image">
	<picture>
		<source media="(min-width: 800px)" srcset="image-large.webp" type="image/webp">
		<source media="(max-width: 800px)" srcset="image-small.webp" type="image/webp">
		<!-- Other sources as specified in the "sources" model attribute... -->
		<img src="image.png" alt="An image using picture" />
	</picture>
	<figcaption>Caption of the image</figcaption>
</figure>

**Note:** The value of the sources in both examples equals:

[
	{
		media: '(min-width: 800px)',
		srcset: 'image-large.webp',
		type: 'image/webp'
	},
	{
		media: '(max-width: 800px)',
		srcset: 'image-small.webp',
		type: 'image/webp'
	}
]

* It integrates with the plugin so images uploaded in the editor automatically render using <picture> if the supports image sources and provides neccessary data.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ImageEditing, typeof ImageUtils];

method afterInit

afterInit: () => void;

class ReplaceImageSourceCommand

class ReplaceImageSourceCommand extends Command {}

Replace image source command.
Changes image source to the one provided. Can be executed as follows:
editor.execute( 'replaceImageSource', { source: 'http://url.to.the/image' } );

constructor

constructor(editor: Editor);

property value

value: string;

method cleanupImage

cleanupImage: (writer: Writer, image: Element) => void;

Cleanup image attributes that are not relevant to the new source.
Removed attributes are: 'srcset', 'sizes', 'sources', 'width', 'height', 'alt'.
This method is decorated, to allow custom cleanup logic. For example, to remove 'myImageId' attribute after 'src' has changed:
replaceImageSourceCommand.on( 'cleanupImage', ( eventInfo, [ writer, image ] ) => { writer.removeAttribute( 'myImageId', image ); } );

method execute

execute: (options: { source: string }) => void;

Executes the command.
execute
Parameter options
Options for the executed command.
Parameter
options.source The image source to replace.

method refresh

refresh: () => void;

class ResizeImageCommand

class ResizeImageCommand extends Command {}

The resize image command. Currently, it only supports the width attribute.

property value

value: { width: string | null; height: string | null };

Desired image width and height.

method execute

execute: (options: { width: string | null }) => void;

Executes the command.

// Sets the width to 50%:
editor.execute( 'resizeImage', { width: '50%' } );

// Removes the width attribute:
editor.execute( 'resizeImage', { width: null } );

Parameter options

Parameter

options.width The new width of the image. execute

method refresh

refresh: () => void;

class ToggleImageCaptionCommand

class ToggleImageCaptionCommand extends Command {}

The toggle image caption command.
This command is registered by as the 'toggleImageCaption' editor command.
Executing this command:
* either adds or removes the image caption of a selected image (depending on whether the caption is present or not), * removes the image caption if the selection is anchored in one.
// Toggle the presence of the caption. editor.execute( 'toggleImageCaption' );
**Note**: Upon executing this command, the selection will be set on the image if previously anchored in the caption element.
**Note**: You can move the selection to the caption right away as it shows up upon executing this command by using the focusCaptionOnShow option:
editor.execute( 'toggleImageCaption', { focusCaptionOnShow: true } );

property value

value: boolean;

method execute

execute: (options?: { focusCaptionOnShow?: boolean }) => void;

Executes the command.
editor.execute( 'toggleImageCaption' );
Parameter options
Options for the executed command.
Parameter
options.focusCaptionOnShow When true and the caption shows up, the selection will be moved into it straight away. execute

method refresh

refresh: () => void;

class UploadImageCommand

class UploadImageCommand extends Command {}

The upload image command.

The command is registered by the plugin as uploadImage and it is also available via aliased imageUpload name.

In order to upload an image at the current selection position (according to the algorithm), execute the command and pass the native image file instance:

this.listenTo( editor.editing.view.document, 'clipboardInput', ( evt, data ) => {
	// Assuming that only images were pasted:
	const images = Array.from( data.dataTransfer.files );

	// Upload the first image:
	editor.execute( 'uploadImage', { file: images[ 0 ] } );
} );

It is also possible to insert multiple images at once:

editor.execute( 'uploadImage', {
	file: [
		file1,
		file2
	]
} );

constructor

constructor(editor: Editor);

Creates an instance of the imageUlpoad command. When executed, the command upload one of the currently selected image from computer.
Parameter editor
The editor instance.

method execute

execute: (options: { file: ArrayOrItem<File> }) => void;

Executes the command.
execute
Parameter options
Options for the executed command.
Parameter
options.file The image file or an array of image files to upload.

method refresh

refresh: () => void;

Interfaces

interface ImageConfig

interface ImageConfig {}

The configuration of the image features. Used by the image features in the @ckeditor/ckeditor5-image package.

ClassicEditor
	.create( editorElement, {
			image: ... // Image feature options.
	} )
	.then( ... )
	.catch( ... );

See .

property insert

insert?: ImageInsertConfig;

The image insert configuration.

property resizeOptions

resizeOptions?: Array<ImageResizeOption>;

The image resize options.

Each option should have at least these two properties:

* name: The name of the UI component registered in the global of the editor, representing the button a user can click to change the size of an image, * value: An actual image width applied when a user clicks the mentioned button ( gets executed). The value property is combined with the (% by default). For instance: value: '50' and resizeUnit: '%' will render as '50%' in the UI.

**Resetting the image size**

If you want to set an option that will reset image to its original size, you need to pass a null value to one of the options. The :original token is not mandatory, you can call it anything you wish, but it must reflect in the standalone buttons configuration for the image toolbar.

ClassicEditor
	.create( editorElement, {
		image: {
			resizeUnit: "%",
			resizeOptions: [ {
				name: 'resizeImage:original',
				value: null
			},
			{
				name: 'resizeImage:50',
				value: '50'
			},
			{
				name: 'resizeImage:75',
				value: '75'
			} ]
		}
	} )
	.then( ... )
	.catch( ... );

**Resizing images using a dropdown**

With resize options defined, you can decide whether you want to display them as a dropdown or as standalone buttons. For the dropdown, you need to pass only the resizeImage token to the . The dropdown contains all defined options by default:

ClassicEditor
	.create( editorElement, {
		image: {
			resizeUnit: "%",
			resizeOptions: [ {
				name: 'resizeImage:original',
				value: null
			},
			{
				name: 'resizeImage:50',
				value: '50'
			},
			{
				name: 'resizeImage:75',
				value: '75'
			} ],
			toolbar: [ 'resizeImage', ... ],
		}
	} )
	.then( ... )
	.catch( ... );

**Resizing images using individual buttons**

If you want to have separate buttons for , pass their names to the instead. Please keep in mind that this time **you must define the additional **:

ClassicEditor
	.create( editorElement, {
		image: {
			resizeUnit: "%",
			resizeOptions: [ {
				name: 'resizeImage:original',
				value: null,
				icon: 'original'
			},
			{
				name: 'resizeImage:25',
				value: '25',
				icon: 'small'
			},
			{
				name: 'resizeImage:50',
				value: '50',
				icon: 'medium'
			},
			{
				name: 'resizeImage:75',
				value: '75',
				icon: 'large'
			} ],
			toolbar: [ 'resizeImage:25', 'resizeImage:50', 'resizeImage:75', 'resizeImage:original', ... ],
		}
	} )
	.then( ... )
	.catch( ... );

**Customizing resize button labels**

You can set your own label for each resize button. To do that, add the label property like in the example below.

* When using the **dropdown**, the labels are displayed on the list of all options when you open the dropdown. * When using **standalone buttons**, the labels will are displayed as tooltips when a user hovers over the button.

ClassicEditor
	.create( editorElement, {
		image: {
			resizeUnit: "%",
			resizeOptions: [ {
				name: 'resizeImage:original',
				value: null,
				label: 'Original size'
				// Note: add the "icon" property if you're configuring a standalone button.
			},
			{
				name: 'resizeImage:50',
				value: '50',
				label: 'Medium size'
				// Note: add the "icon" property if you're configuring a standalone button.
			},
			{
				name: 'resizeImage:75',
				value: '75',
				label: 'Large size'
				// Note: add the "icon" property if you're configuring a standalone button.
			} ]
		}
	} )
	.then( ... )
	.catch( ... );

**Default value**

The following configuration is used by default:

resizeOptions = [
	{
		name: 'resizeImage:original',
		value: null,
		icon: 'original'
	},
	{
		name: 'resizeImage:25',
		value: '25',
		icon: 'small'
	},
	{
		name: 'resizeImage:50',
		value: '50',
		icon: 'medium'
	},
	{
		name: 'resizeImage:75',
		value: '75',
		icon: 'large'
	}
];

property resizeUnit

resizeUnit?: 'px' | '%';

The available options are 'px' or '%'.
Determines the size unit applied to the resized image.
ClassicEditor .create( editorElement, { image: { resizeUnit: 'px' } } ) .then( ... ) .catch( ... );
This option is used by the feature.
'%'

property styles

styles?: ImageStyleConfig;

The plugin requires a list of the to work properly. The default configuration is provided (listed below) and can be customized while creating the editor instance.
# **Command**
The is configured based on the defined options, so you can change the style of the selected image by executing the following command:
editor.execute( 'imageStyle' { value: 'alignLeft' } );
# **Buttons**
All of the image style options provided in the configuration are registered in the with the "imageStyle:" prefixes and can be used in the . The buttons available by default depending on the loaded plugins are listed in the next section.
Read more about styling images in the .
# **Default options and buttons**
If the custom configuration is not provided, the default configuration will be used depending on the loaded image editing plugins.
* If both and plugins are loaded (which is usually the default editor configuration), the following options will be available for the toolbar configuration. These options will be registered as the buttons with the "imageStyle:" prefixes.
const imageDefaultConfig = { styles: { options: [ 'inline', 'alignLeft', 'alignRight', 'alignCenter', 'alignBlockLeft', 'alignBlockRight', 'block', 'side' ] } };
* If only the plugin is loaded, the following buttons (options) and groups will be available for the toolbar configuration. These options will be registered as the buttons with the "imageStyle:" prefixes.
const imageDefaultConfig = { styles: { options: [ 'block', 'side' ] } };
* If only the plugin is loaded, the following buttons (options) and groups will available for the toolbar configuration. These options will be registered as the buttons with the "imageStyle:" prefixes.
const imageDefaultConfig = { styles: { options: [ 'inline', 'alignLeft', 'alignRight' ] } };
Read more about the .
# **Custom configuration**
The image styles configuration can be customized in several ways:
* Any of the can be loaded by the reference to its name as follows:
ClassicEditor .create( editorElement, { image: { styles: { options: [ 'alignLeft', 'alignRight' ] } } } );
* Each of the can be customized, e.g. to change the icon, title or CSS className of the style. The feature also provides several to choose from.
import customIcon from 'custom-icon.svg'; // ... ClassicEditor.create( editorElement, { image: styles: { options: { // This will only customize the icon of the "block" style. // Note: 'right' is one of default icons provided by the feature. { name: 'block', icon: 'right' }, // This will customize the icon, title and CSS class of the default "side" style. { name: 'side', icon: customIcon, title: 'My side style', className: 'custom-side-image' } } } } );
* If none of the works for the integration, it is possible to define independent custom styles, too.
See the documentation about the image style to define the custom image style configuration properly.
import redIcon from 'red-icon.svg'; import blueIcon from 'blue-icon.svg'; // ... ClassicEditor.create( editorElement, { image: styles: { // A list of completely custom styling options. options: [ { name: 'regular', modelElements: [ 'imageBlock', 'imageInline' ], title: 'Regular image', icon: 'full', isDefault: true }, { name: 'blue', modelElements: [ 'imageInline' ], title: 'Blue image', icon: blueIcon, className: 'image-blue' }, { name: 'red', modelElements: [ 'imageBlock' ], title: 'Red image', icon: redIcon, className: 'image-red' } ] } } );

toolbar?: Array<string | ImageStyleDropdownDefinition>;

Items to be placed in the image toolbar. This option is used by the feature.
Assuming that you use the following features:
* (with a default configuration), * , * ,
the following toolbar items will be available in : * 'imageTextAlternative', * 'toggleImageCaption', * , * ,
so you can configure the toolbar like this:
const imageConfig = { toolbar: [ 'imageStyle:inline', 'imageStyle:wrapText', 'imageStyle:breakText', '|', 'toggleImageCaption', 'imageTextAlternative' ] };
Besides that, the ImageStyle plugin allows to define a while configuring the toolbar.
The same items can also be used in the .
Read more about configuring toolbar in .

property upload

upload?: ImageUploadConfig;

The image upload configuration.

Type Aliases

type ImageUploadCompleteEvent

type ImageUploadCompleteEvent = {
    name: 'uploadComplete';
    args: [data: ImageUploadCompleteData];
};

An event fired when an image is uploaded. You can hook into this event to provide custom attributes to the based on the data from the server.
const imageUploadEditing = editor.plugins.get( 'ImageUploadEditing' ); imageUploadEditing.on( 'uploadComplete', ( evt, { data, imageElement } ) => { editor.model.change( writer => { writer.setAttribute( 'someAttribute', 'foo', imageElement ); } ); } );
You can also stop the default handler that sets the src and srcset attributes if you want to provide custom values for these attributes.
imageUploadEditing.on( 'uploadComplete', ( evt, { data, imageElement } ) => { evt.stop(); } );
**Note**: This event is fired by the plugin.
~ImageUploadEditing#uploadComplete
Parameter data
The uploadComplete event data.

Package Files (42)

Dependencies (11)

Dev Dependencies (0)

No dev dependencies.

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@ckeditor/ckeditor5-image.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@ckeditor/ckeditor5-image)

HTML

<a href="https://www.jsdocs.io/package/@ckeditor/ckeditor5-image"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated just now.
Package analyzed in 4357 ms.
Missing or incorrect documentation? Open an issue for this package.

@ckeditor/ckeditor5-image

Install

Overview

Index

Classes

Interfaces

Type Aliases

Classes

class AutoImage

property pluginName

property requires

method init

class Image

property pluginName

property requires

class ImageBlock

property pluginName

property requires

class ImageBlockEditing

property pluginName

property requires

method init

class ImageCaption

property pluginName

property requires

class ImageCaptionEditing

property pluginName

property requires

method init

class ImageCaptionUI

property pluginName

property requires

method init

class ImageCaptionUtils

property pluginName

property requires

method getCaptionFromImageModelElement

method getCaptionFromModelSelection

method matchImageCaptionViewElement

Returns

class ImageCustomResizeUI

property pluginName

property requires

method destroy

class ImageEditing

property pluginName

property requires

method init

class ImageInline

property pluginName

property requires

class ImageInsert

property pluginName

property requires

class ImageInsertUI

property dropdownView

property isImageSelected

property pluginName

property requires

method init

method registerIntegration

class ImageInsertViaUrl

property pluginName

property requires

class ImageResize

property pluginName

property requires

class ImageResizeButtons

property pluginName

property requires

method init

class ImageResizeEditing

property pluginName

property requires

method afterInit

method init

class ImageResizeHandles

property pluginName

property requires

method init