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

  • resizeOptions : Array.<ImageResizeOption>

    The image resize options.

    See source

    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

    The available options are 'px' or '%'.

    See source

    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 : Array.<ImageStyleFormat>

    Available image styles.

    See source

    The default value is:

    const imageConfig = {
	styles: [ 'full', 'side' ]
};

    which configures two default styles:

    • the "full" style which does not apply any class, e.g. for images styled to span 100% width of the content,
    • the "side" style with the .image-style-side CSS class.

    See defaultStyles to learn more about default styles provided by the image feature.

    The default styles can be customized, e.g. to change the icon, title or CSS class of the style. The feature also provides several default icons to choose from.

    import customIcon from 'custom-icon.svg';

// ...

const imageConfig = {
	styles: [
		// This will only customize the icon of the "full" style.
		// Note: 'right' is one of default icons provided by the feature.
		{ name: 'full', 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 styles is good enough, it is possible to define independent custom styles, too:

    import { icons } from 'ckeditor5/src/core';

const fullSizeIcon = icons.objectCenter';
const sideIcon = icons.objectRight';

// ...

const imageConfig = {
	styles: [
		// A completely custom full size style with no class, used as a default.
		{ name: 'fullSize', title: 'Full size', icon: fullSizeIcon, isDefault: true },

		{ name: 'side', title: 'To the side', icon: sideIcon, className: 'side-image' }
	]
};

    Note: Setting title to one of localizedDefaultStylesTitles will automatically translate it to the language of the editor.

    Read more about styling images in the Image styles guide.

    The feature creates commands based on defined styles, so you can change the style of a selected image by executing the following command:

    editor.execute( 'imageStyle' { value: 'side' } );

    The feature also creates buttons that execute the commands. So, assuming that you use the default image styles setting, you can configure the image toolbar (or any other toolbar) to contain these options:

    const imageConfig = {
	toolbar: [ 'imageStyle:full', 'imageStyle:side' ]
};

  • toolbar : Array.<String>

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

    See source

    Assuming that you use the following features:

    three toolbar items will be available in ComponentFactory: 'imageStyle:full', 'imageStyle:side', and 'imageTextAlternative' so you can configure the toolbar like this:

    const imageConfig = {
	toolbar: [ 'imageStyle:full', 'imageStyle:side', '|', 'imageTextAlternative' ]
};

    Of course, the same buttons can also be used in the main editor toolbar.

    Read more about configuring toolbar in toolbar.

  • upload : ImageUploadConfig

    The image upload configuration.

    See source

  • insert : ImageInsertConfig

    protected

    The image insert configuration.

    See source