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

  • 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 fullSizeIcon from '@ckeditor/ckeditor5-core/theme/icons/object-center.svg';
import sideIcon from '@ckeditor/ckeditor5-core/theme/icons/object-right.svg';

// ...

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

    Image upload configuration.

    See source