Contribute to this guide

guideImage 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.

The actual styling of the images is the integrator’s job. CKEditor 5 WYSIWYG editor comes with some default styles, but they will only be applied to the images inside the editor. The integrator needs to style them appropriately on the target pages.

You can find the source of the default styles applied by the editor here: ckeditor5-image/theme/imagestyle.css.

Read more about styling the content of the editor.

# 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.

The ImageStyle plugin does not provide any mechanism to apply a default CSS class to newly inserted images. The initial image appearance should be handled by the integrator by defining the proper custom content styles. If desired, the default image appearance customization can be done by overriding the following CSS rules:

  • .ck-content .image-inline for the inline images,
  • .ck-content .image for the block images.

# 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.

All of the default editor builds support both block and inline images, but it is also possible to disable one of these types.

# 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.

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.

The distinction made above is purely theoretical. Setting up both semantical and presentational styles is done in exactly the same way, using the ImageConfig#styles configuration.

# 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.

Try to understand what use cases you system needs to support and define semantic options accordingly. Defining useful and clear styles is one of the steps towards a good user experience and clear, portable output. The “side image” in the example below is displayed as a floated image on wide screens and as a normal image on low resolution screens (e.g. mobile browsers).

While semantical styles can be combined with manual image resizing, these features were not designed to be used together, as semantical styles usually also affect the image size.

If you want to enable image resizing, use presentational image styles instead or define custom semantical styles to make sure that there are no conflicts with the image resizing feature.

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 Block image - a representation of a block image with no style-related CSS class,
  • an inline image Inline image - a representation of an inline image with no style-related CSS class,
  • a side image 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.

Walking the capitals of Europe: Coat of arms of Warsaw Warsaw

If you enjoyed my previous articles in which we discussed wandering around Copenhagen and Vilnius, you’ll definitely love exploring Warsaw.

The panorama of Warsaw

Time to put comfy sandals on!

The best time to visit the city is in July and August when it’s cool enough to not break a sweat and hot enough to enjoy summer. The city which has quite a combination of both old and modern textures is located by the river of Vistula.

Warsaw Castle Square

The historic See on Google Maps Old Town, which was reconstructed after World War II, with its late 18th century characteristics, is a must-see. You can start your walk from the See on Google Maps Nowy Świat Street which will take you straight to the Old Town.

Then you can go to the See on Google Maps Powiśle area and take a walk on the newly renovated promenade on the riverfront. There are also lots of cafes, bars and restaurants where you can shake off the exhaustion of the day. On Sundays, there are many parks where you can enjoy nature or listen to pianists from around the world playing Chopin.

Photos: Wikipedia.org.

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.

Presentational image styles should be combined with the optional image resizing feature as these features were designed to be used together. The image width is then controlled by the image resize feature, while the alignment is controlled by the image style feature.

If you do not enable the image resize feature in your setup while using the default presentational styles, your images will always retain their original sizes (up to 100% of the editor width) so the alignment may not be visible.

If you do not want to enable image resizing, you can use semantical styles to set the image dimensions.

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 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 Inline image aligned to the left - 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' Image aligned to the left,
    • 'align-right' Image aligned to the right.
  • Images placed between the paragraphs Centered image - block images without the CSS float property. It contains following image styles:
    • 'align-block-left' Block image aligned to the left,
    • 'align-block-right' Block image aligned to the right,
    • 'block' Centered block image - 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:

Walking the capitals of Europe: Coat of arms of Warsaw Warsaw

If you enjoyed my previous articles in which we discussed wandering around Copenhagen and Vilnius, you’ll definitely love exploring Warsaw.

The panorama of Warsaw

Time to put comfy sandals on!

The best time to visit the city is in July and August when it’s cool enough to not break a sweat and hot enough to enjoy summer. The city which has quite a combination of both old and modern textures is located by the river of Vistula.

Warsaw Castle Square

The historic See on Google Maps Old Town, which was reconstructed after World War II, with its late 18th century characteristics, is a must-see. You can start your walk from the See on Google Maps Nowy Świat Street which will take you straight to the Old Town.

Then you can go to the See on Google Maps Powiśle area and take a walk on the newly renovated promenade on the riverfront. There are also lots of cafes, bars and restaurants where you can shake off the exhaustion of the day. On Sundays, there are many parks where you can enjoy nature or listen to pianists from around the world playing Chopin.

Photos: Wikipedia.org.

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( ... );

At the moment it is not possible to apply multiple styles (classes) to the image at the same time. To apply multiple CSS rules to the image (e.g. a red border AND a left alignment), you should probably consider using the semantical styles.

# 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.

Reusing (or modifying) predefined styles has the following advantage: CKEditor 5 will use its official translations provided for the defined button titles.

# Demo

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

Handshake over the clouds

Space shuttle
High over the world

Rivalry is what drove early space exploration. After WW2, the two superpowers on opposite sides of the world set off on a race from the planet’s surface into the cosmic void. For most of the time, they would compete and race each other. But after the Soviets set up permanent space stations on Low Earth Orbit and the Americans put a man on the Moon, the time came to hold back the competition and cooperate.


Leonov and Slayton in orbit
Friends not foes

The first step on the eventual road to building International Space Station was the Apollo Soyuz Test Project. A specially redesigned pair of the Apollo and Soyuz spacecraft met in orbit and docked together in 1975. Their respective commanders, Thomas Stafford and Alexei Leonov shook hands inside the airlock brought to orbit by Apollo. They remained docked for two days.

Norman Thagard
Norman Thagard

The ASTP mission was a great step forward, but for a long time an only one. It also marked the end of an era, as the Apollo flown then was the last of its kind. Six years later an era of space shuttles came. These new cosmic planes also marked the return to cooperation. In 1994 Russia and the USA started the Shuttle-Mir program, which saw Russians riding shuttles and Americans visiting Mir space station, with Norman Thagard to be the first US citizen to ever fly a Soyuz. This was the preliminary phase and a technology testbed before launching the first module of the International Space Station in 1998.

The next step in collaboration:
International Space

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

We recommend using the official CKEditor 5 inspector for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

# Contribute

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