Image styles

# Overview

This package allows for adjusting the image appearance by:

• Applying CSS classes - adding a particular predefined or custom CSS class or removing any style-related CSS class,
• Managing the HTML representation by changing the image type from inline to block and vice versa. Applying a style may change the type of the image, depending on the configuration of the style.

# Image classes

The styles applied to the image can either add or remove the style-related class from it. This behavior depends on the particular configuration of the ImageStyleOptionDefinition. Only the definition with the isDefault flag set to true will remove any applied image style-related class.

# Inline and block images

Images in the editor can be displayed as either inline or block.

The inline type images are represented as inline HTML elements and can be inserted in the middle of a paragraph or in a link just like a regular text. The HTML representation of the inline image looks like this:

• <span class=”image-style-class”><img></img></span> in the editable,
• <img class=”image-style-class”></img> in the HTML content retrieved by the getData method.

Block type images, on the other hand, can be inserted only between other blocks like paragraphs, tables or media. The HTML representation of the block image looks like this:

• <figure class=”image image-style-class”><img></img></figure>.

Switching between these two types of images can be executed by applying/removing a style from the image: Each of the defined style options provides a list of the image types which it can be applied to. Applying a style may change the type of the image, depending on the configuration of the style.

When a new image is inserted, the editor will, by default, choose the optimal image type based on the context of the insertion (e.g. the current selection/position and availability of plugins). The default type of the newly inserted image can be controlled using the image.insert.type configuration.

# UI

Application of a style can be executed by using one of the toolbar buttons created by the ImageStyle plugin. Each of the defined styles (both default and custom) will be registered under the name imageStyle:image-style-name in the ComponentFactory and can be added to the image or main toolbar by referencing to this name.

The default image toolbar has its standard configuration already set in the predefined builds.

• The default UI of the classic, inline, balloon and balloon block builds consists of a set of buttons to apply only the semantical styles to support creating a structured content. See a live example.
• The document editor build UI uses several buttons for applying presentational styles and also uses the semantical styles to reset the image appearance to default. See a live example.

It is also possible to create a completely custom image styles UI, setting your own icons and tooltips, and grouping the image style buttons into the custom drop-downs. Read more about it in the customizing the image styles UI section of this guide.

# Approaches to styling images

CKEditor5 offers two basic approaches to styling the images:

• A particular style can define the image “type”, so it can be styled for example as an avatar, a banner or an emoticon. It will be called a “semantical style”, since it refers to the purpose of the particular image.
• On the other hand, sometimes the user should be able to granularly control how an image is presented thanks to the ability to set the size and alignment separately and completely arbitrarily. The style that defines the image alignment will be called a “presentational” one, since it refers only to the appearance of the image.

# Semantical styles

A semantical style lets the user choose from predefined appearances of the images. The user is not able to set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the WYSIWYG editor integration. Check the list of the available semantical styles in the table below. Semantical styles give the integrator an ability to put a wide range of predefined image appearances at the user’s disposal. This gives the developer control over how the users style their images and makes the user’s life easier by setting multiple properties at once.

As the most of the predefined editor builds support editing a structured content which requires passing the control over the possible image appearances to the developer, they introduce a UI containing a set of buttons applying the semantical styles (taken from the default styles listed below).

The example below presents an editor with such a basic configuration. There are three types of the images:

• a block image - a representation of a block image with no style-related CSS class,
• an inline image - a representation of an inline image with no style-related CSS class,
• a side image - a semantical style applying the image-style-side CSS class to it.

You can change the style of an individual image using the contextual toolbar invoked after an image is clicked.

The editor above does not require any configuration, using one of the following builds: classic, inline, balloon or balloon-block, for example:

import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';

ClassicEditor
    .create( document.querySelector( '#editor' ) )
    .then( ... )
    .catch( ... );

# Presentational styles

Presentational styles do not relate to any special meaning of the content. They directly control the visual aspect of an image. The default available presentational styles determine the image alignment behavior. Check the list of the available semantical styles in the table below.

The sample editor below uses predefined presentational image styles represented by buttons grouped in the drop-downs by the way the image is displayed in the document:

• Inline images - displayed inside a line of text. It is a default style for the inline images and it does not apply any CSS class to the image.
• Images wrapped with text - these are the images with the CSS float property. They can be either in the inline or block mode, but to keep the valid HTML output, the block images (wrapped with the <figure> tags) can only be placed before or after paragraphs, not in the middle of one. It contains the following image styles:
  • 'align-left' ,
  • 'align-right' .
• Images placed between the paragraphs - block images without the CSS float property. It contains following image styles:
  • 'align-block-left' ,
  • 'align-block-right' ,
  • 'block' - this style is the default one for block images and it does not apply any CSS class to the image.

You can change the style of an individual image using the contextual toolbar invoked after an image is clicked.

In addition to the above, the sample is configured to use the image resize feature with three resize options available: 'resizeImage:original', 'resizeImage:50' and 'resizeImage:75'. They allow you to set the image width in the editor to the original image size (up to 100% of the editor window width), 50% and 75% respectively. You can also use the resize handles to set a custom size of the image.

See the result below:

This set of buttons and styles is available by default in the predefined document editor build and does not require any additional customization:

import DecoupledEditor from '@ckeditor/ckeditor5-editor-decoupled/src/decouplededitor';

DecoupledEditor.
    .create( document.querySelector( '#editor' ) )
    .then( ... )
    .catch( ... );

# Configuring the styles

There are three ways of defining the image styles in the editor configuration:

• using one of the predefined default styles,
• modifying one of the styles mentioned above (you can change the class it applies to the image, the icon, the tooltip and the supported image type),
• defining a completely custom image style.

# Demo

The editor example below shows the possibilities of customizing the image visual representation and customizing image styles UI (icons, tooltips and drop-downs).

The editor presented above uses custom image styles, custom image toolbar configuration with declarative drop-downs, and some modified default styles. You can find some more examples of using and modifying these styles in the config.image.styles API documentation.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        ...
        image: {
            styles: {
                // Defining custom styling options for the images.
                options: [ {
                    name: 'side',
                    icon: sideIcon,
                    title: 'Side image',
                    className: 'image-side',
                    modelElements: [ 'imageBlock' ]
                }, {
                    name: 'margin-left',
                    icon: leftIcon,
                    title: 'Image on left margin',
                    className: 'image-margin-left',
                    modelElements: [ 'imageInline' ]
                }, {
                    name: 'margin-right',
                    icon: rightIcon,
                    title: 'Image on right margin',
                    className: 'image-margin-right',
                    modelElements: [ 'imageInline' ]
                },
                // Modifying icons and titles of the default inline and
                // block image styles to reflect its real appearance.
                {
                    name: 'inline',
                    icon: inlineIcon
                }, {
                    name: 'block',
                    title: 'Centered image',
                    icon: centerIcon
                } ]
            },
            toolbar: [ {
                // Grouping the buttons for the icon-like image styling
                // into one drop-down.
                name: 'imageStyle:icons',
                items: [
                    'imageStyle:margin-left',
                    'imageStyle:margin-right',
                    'imageStyle:inline'
                ],
                defaultItem: 'imageStyle:margin-left'
            }, {
                // Grouping the buttons for the regular
                // picture-like image styling into one drop-down.
                name: 'imageStyle:pictures',
                items: [ 'imageStyle:block', 'imageStyle:side' ],
                defaultItem: 'imageStyle:block'
            }, '|', 'toggleImageCaption', 'linkImage'
            ]
        }
    } )
    .then( ... )
    .catch( ... );

It also applies multiple CSS rules to not only display custom image styles (the 'image-margin-right', 'image-margin-left' and 'image-side' classes) properly, but also to provide the default content styles, so the appearance of headers, paragraphs, links, captions and newly inserted images is consistent.

The most important rules regarding the image styling are presented below. You can see the complete content stylesheet here.

/* Defining the default content styles for the block images.
This is what the newly inserted image without any
style-specific class will look like. */
.ck-content .image {
    margin-top: 50px;
    margin-bottom: 50px;
}
.ck-content .image img {
    border-radius: 50%;
    width: 180px;
    height: 180px;
    object-fit: cover;
    filter: grayscale(100%) brightness(70%);
    box-shadow: 10px 10px 30px #00000078;
}
.ck-content .image::before {
    content: '';
    width: 100%;
    height: 100%;
    background-color: #1138b0;
    top: 5%;
    left: 5%;
    position: absolute;
    border-radius: 50%;
}
.ck-content .image::after {
    content: '';
    width: 200%;
    height: 200%;
    background-image: url(../../assets/img/image-context.svg);
    background-size: contain;
    background-repeat: no-repeat;
    position: absolute;
    top: -60%;
    pointer-events: none;
    left: -60%;
}

/* Defining the default content styles for the inline images.
This is what the newly inserted image without any
style-specific class will look like. */
.ck-content .image-inline {
    margin: 0 4px;
    vertical-align: middle;
    border-radius: 12px;
}
.ck-content .image-inline img {
    width: 24px;
    max-height: 24px;
    min-height: 24px;
    filter: grayscale(100%);
}

/* Defining the custom content styles for the images
placed on the side of the editing area. */
.ck-content .image.image-side {
    float: right;
    margin-right: -200px;
    margin-left: 50px;
    margin-top: -50px;
}
.ck-content .image.image-side img {
    width: 360px;
    height: 360px;
}

/* Defining the custom content styles for the images
placed on the editor margins. */
.ck-content .image-inline.image-margin-left,
.ck-content .image-inline.image-margin-right {
    position: absolute;
    margin: 0;
    top: auto;
}
.ck-content .image-inline.image-margin-left {
    left: calc( -12.5% - var(--icon-size) / 2 );
}
.ck-content .image-inline.image-margin-right {
    right: calc( -12.5% - var(--icon-size) / 2 );
}
.ck-content .image-inline.image-margin-left img,
.ck-content .image-inline.image-margin-right img {
    filter: none;
}

/* Defining the custom content styles for the image captions. */
.ck-content .image > figcaption {
    z-index: 1;
    position: absolute;
    bottom: 20px;
    left: -20px;
    font-style: italic;
    border-radius: 41px;
    background-color: #ffffffe8;
    color: #1138b0;
    padding: 5px 12px;
    font-size: 13px;
    box-shadow: 0 0 18px #1a1a1a26
}

# Ready-to-use styles

The ImageStyle plugin provides a set of default styles depending on the loaded plugins. The table below presents the availability of these styles and the image behavior caused by an application of a particular style.

Style name	Required plugins	Converts to	Applies class	Type
"block"	ImageBlock	block	removes all classes (default style)	semantical
"inline"	ImageInline	inline	removes all classes (default style)	semantical
"side"	ImageBlock	block	image-style-side	semantical
"alignLeft"	any	-	image-style-align-left	presentational
"alignRight"	any	-	image-style-align-right	presentational
"alignBlockLeft"	ImageBlock	block	image-style-align-block-left	presentational
"alignBlockRight"	ImageBlock	block	image-style-align-block-right	presentational
"alignCenter"	ImageBlock	block	image-style-align-center	presentational

# Installation

This feature is available in all ready-to-use editor builds. If your integrations uses a custom editor build, check out the image feature installation guide to learn how to enable this feature.

# Common API

The ImageStyle plugin registers:

• A button for each defined style, for example: 'imageStyle:block' and 'imageStyle:side' (to use in the image toolbar).

• The 'imageStyle' command that accepts a value based on the image.styles configuration option (for example, 'block' and 'side'):

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

# Contribute

The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image.