CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Interface

ImageConfig (image)

@ckeditor/ckeditor5-image/src/image

interface
See source

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 all editor options.

Filtering

Properties

  • insert : ImageInsertConfig

    See source

    The image insert configuration.

  • resizeOptions : Array.<ImageResizeOption>

    See source

    The image resize options.

    Each option should have at least these two properties:

    • name: The name of the UI component registered in the global component factory 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 (ResizeImageCommand gets executed). The value property is combined with the config.image.resizeUnit (% 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 config.image.toolbar. 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 each option, pass their names to the config.image.toolbar instead. Please keep in mind that this time you must define the additional icon property:

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

  • resizeUnit : String

    See source

    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 ImageResize feature.

    Defaults to '%'

  • styles : ImageStyleConfig

    See source

    The ImageStyle plugin requires a list of the image style options to work properly. The default configuration is provided (listed below) and can be customized while creating the editor instance.

    Command

    The imageStyleCommand 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 UI components factory with the "imageStyle:" prefixes and can be used in the image toolbar configuration. The buttons available by default depending on the loaded plugins are listed in the next section.

    Read more about styling images in the Image styles guide.

    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 ImageBlockEditing and ImageInlineEditing 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 ImageBlockEditing 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 ImageInlineEditing 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 default styling options.

    Custom configuration

    The image styles configuration can be customized in several ways:

    • Any of the default styling options can be loaded by the reference to its name as follows:

      ClassicEditor
	.create( editorElement, {
		image: {
			styles: {
				options: [ 'alignLeft', 'alignRight' ]
			}
		}
	} );

    • Each of the default image style options can be customized, e.g. to change the icon, title or CSS className of the style. The feature also provides several default icons 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 default image style options works for the integration, it is possible to define independent custom styles, too.

    See the documentation about the image style options 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>

    See source

    Items to be placed in the image toolbar. This option is used by the ImageToolbar feature.

    Assuming that you use the following features:

    the following toolbar items will be available in ComponentFactory:

    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 custom drop-down while configuring the toolbar.

    The same items can also be used in the main editor toolbar.

    Read more about configuring toolbar in toolbar.

  • upload : ImageUploadConfig

    See source

    The image upload configuration.