CKEditor Ecosystem Documentation
Search
Contribute to this guide
Home/CKEditor 5/Features

guideResizing images

The image resize feature lets you change the width of images in your content. It is implemented by the ImageResize plugin.

# Methods to resize images

The editor offers different ways to resize images either by using “resize handles” or by using dedicated UI components – either a dropdown or standalone buttons.

The ImageResize plugin enables the four resize handles displayed over the selected image. The user can resize the image by dragging them. You can configure the feature to use either percentage (default) or pixel values.

The plugin also gives you the ability to change the size of the image through the on-click image toolbar. You can set an optional static configuration with resizeOptions and choose whether you want to use a dropdown or a set of standalone buttons.

# Using resize handles

In this case, you can resize an image by dragging square handles displayed in each of its corners. After you enable image resizing, this option does not require any additional configuration.

Use the corner handles to resize the image and adjust it to the text as needed. You can also use the alignment options from the image toolbar Image align to achieve the desired effect.

Images can also be pre-resized using styling, as shown below (the last three images are hard-set to 28% for visual consistency).

Talking birds

There are many species of birds that can mimic human speech. Among those, parrots are the most widespread in popular culture, although other birds like crows, mynas, or starlings can, too, mimic the human voice. Some of those can only repeat a few words while others have extensive vocabularies of over a thousand words.

The oldest recorded talking bird was probably a parakeet living 2,500 years ago, described by the Greek historian Ctesias. While the birds’ ability to repeat human words is indisputable, there is a debate about whether they understand the language at all and if so — to what extent.

Well-known talking birds species

The sun parakeet (Aratinga solstitialis), also known in aviculture as the sun conure, is a medium-sized, vibrantly colored parrot native to northeastern South America. Sadly, the species is endangered due to loss of habitat and hunting for trade.

Sun parakeets are social birds, forming large flocks, communicating both verbally and non-verbally, and flying large distances together. Even though they are regarded as talking birds, their speech and ability to learn tricks in captivity are quite moderate.

 Listen to this sun conure, who does not want to be stroked.

The cockatiel (Nymphicus hollandicus), also known as the quarrion, is a small parrot originating from Australia. Those cute birds with a characteristic tip on their heads are highly appreciated as household pets all around the world. They should be treated with great care.

Some consider cockatiels to be difficult to train in the arcana of human speech, but in fact, their soft voice requires better skills from the trainer to understand what they mimic.

 Listen to Butters, the talking cockatiel.

The budgerigar (Melopsittacus undulatus) is a small, long-tailed, seed-eating parrot usually nicknamed the budgie and known in American English as the parakeet. They are often kept as pets — even more so than cockatiels. Males are among the top five parrot species as regards the ability to talk. Their mimicry is impressive: a male parakeet owned by Camille Jordan appeared in the 1995 Guinness World Records book as the bird with the largest vocabulary, consisting of 1,728 words!

 Listen to this amazing budgie named Kiwi, using three dozen words.

For clarity, all demos in this guide present a limited set of features. Visit the feature-rich editor example to see more in action.

You can configure resizing images by handles in two different ways in the CKEditor 5 WYSIWYG editor:

  • By installing the ImageResize plugin. It contains all needed features (ImageResizeEditing, ImageResizeHandles, ImageResizeButtons) as described in the installation of this guide.

  • By installing the combination of ImageResizeEditing and ImageResizeHandles plugins. This will not load the unnecessary ImageResizeButtons plugin:

import { Image, ImageResizeEditing, ImageResizeHandles } from '@ckeditor/ckeditor5-image';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image, ImageResizeEditing, ImageResizeHandles, /* ... */ ],
        // More of editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

Both ways enable resize handles by default.

# Using resize dropdown

In this case, the user can choose from a set of predefined options. You can display these options as a dropdown in the image toolbar available after the user clicks the image.

To use this option, you need to enable image resizing and configure the available resize options. Then add the dropdown to the image toolbar configuration.

const imageConfiguration = {
    resizeOptions: [
        {
            name: 'resizeImage:original',
            value: null,
            label: 'Original'
        },
        {
            name: 'resizeImage:40',
            value: '40',
            label: '40%'
        },
        {
            name: 'resizeImage:60',
            value: '60',
            label: '60%'
        }
    ],
    toolbar: [ 'resizeImage', /* ... */ ]
}

Try out the live demo of the resize dropdown Image resize available in the image toolbar:

Toco toucans’ big beaks

Toucans take their name from the Tupi natives’ word tukana. They are best known for their prominent, colorful beaks and can be found in the tropical rainforest of South America. The toco toucans with their bright orange beaks are probably one of the most recognizable birds in the world.

The birds nest in trees. As they are not the best fliers, they prefer to hop from tree to tree instead. They can grow up to 25 inches while their beaks can achieve an impressive length of 7 inches. The beaks are small, though, when the birds hatch and only grow later. Large as they are, toucans’ beaks are very light. The birds use them to attract mates and fence off rivals.

Images in the example below were prepared to match the exact aspect ratios, so they can be displayed together, with equal heights.

If you want to define the possible aspect ratios of the inserted images, for example, allow the user to insert 1:1 and 40% width, and 1:2 and 20% width images, you should use the image style feature.

The example of CSS fixing the image aspect ratio is in the last example of this guide.

# Using standalone resize buttons

In this case, the resize options are displayed as separate buttons. The benefit of this solution is the smoothest UX as the user needs just one click to resize an image.

To use this option, you need to enable image resizing and configure the available resize options. Then add appropriate buttons to the image toolbar configuration.

const imageConfiguration = {
    resizeOptions: [
        {
            name: 'resizeImage:original',
            value: null,
            icon: 'original'
        },
        {
            name: 'resizeImage:50',
            value: '50',
            icon: 'medium'
        },
        {
            name: 'resizeImage:75',
            value: '75',
            icon: 'large'
        }
    ],
    toolbar: [
        'resizeImage:50',
        'resizeImage:75',
        'resizeImage:original',
        // More toolbar options.
        // ...
    ]
}

Try out the live demo of the individual resize buttons Image resize available in the image toolbar:

Being a bee-eater can be fancy!

Bee-eaters are moderately large birds (depending on the species, they reach 6 to 14 inches) that can be found in tropical and subtropical areas of Europe, Asia, Africa, and Australia. They are predominantly brilliant green with additional red, yellow, purple, and blue tones.

The birds use their strong, medium-length, pointed beaks to catch insects — mostly bees (hence the name) and wasps. Bee-eaters are fierce hunters, able to catch their meal mid-air. They are very social. Their colonies are large, usually with over 100 members, sometimes as many as 200 if the conditions permit it. Scientists believe bee-eaters can recognize their keen — parents and siblings — by voice.

# Disabling image resize handles

If you want to configure the editor in such a way that the user can only resize images by buttons, you can do so by omitting the ImageResizeHandles plugin.

As a result, your plugin setup should look like this: plugins: [ 'ImageResizeEditing', 'ImageResizeButtons', /* ... */ ] as opposed to plugins: [ 'ImageResize', /* ... */ ].

This will enable the image resize feature only through the chosen UI: either a dropdown or standalone buttons in the image toolbar.

import { Image, ImageResizeButtons, ImageResizeEditing, ImageToolbar } from '@ckeditor/ckeditor5-image';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image, ImageResizeEditing, ImageResizeButtons, ImageToolbar, /* ... */ ],
        image: {
            resizeOptions: [
            {
                name: 'resizeImage:original',
                value: null,
                icon: 'original'
            },
            {
                name: 'resizeImage:50',
                value: '50',
                icon: 'medium'
            },
            {
                name: 'resizeImage:75',
                value: '75',
                icon: 'large'
            }
        ],
        toolbar: [
            'resizeImage:50',
            'resizeImage:75',
            'resizeImage:original',
            // More toolbar options.
            // ...
        ] }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Markup and styling

When you resize an image, the inline width style is used and the editor assigns the image_resized class to the <figure> element:

<figure class="image image_resized" style="width: 75%;">
    <img src="..." alt="...">
</figure>

The image_resized class is used to disable max-width assigned by the image styles if one is applied to this image. For instance, the “side image” style is defined like this:

.ck-content .image-style-side {
    max-width: 50%;
    float: right;
    margin-left: var(--ck-image-style-spacing);
}

And the max-width gets overridden by the following rule:

.ck-content .image.image_resized {
    max-width: 100%;
}

Another concern when styling resized images is that by default, CKEditor 5 uses display: table on <figure class="image"> elements to make it take up the size of the <img> element inside it. Unfortunately, browsers do not yet support using max-width and width on the same element if it is styled with display: table. Therefore, display: block needs to be used when resizing the image:

.ck-content .image.image_resized {
    display: block;
    box-sizing: border-box;
}

.ck-content .image.image_resized img {
    width: 100%;
}

.ck-content .image.image_resized > figcaption {
    display: block;
}

# Using pixel values instead of percentage width

Using percentage widths ensures that the content stays responsive when displayed in places other than the WYSIWYG editor. When the user makes an image take up, for example, 60% of the content’s width in the editor, if you ever change the width of the target page (where this content is displayed), the image will still take up 60% of that space. The same is true if the page is responsive and adjusts to the viewport’s width.

If you configured the editor to use pixel values, the image could take up, for example, too much space after you introduced a new layout for your website.

However, there are cases where you may prefer pixel values. You can thus configure the editor to use them by setting the config.image.resizeUnit option:

ClassicEditor
    .create( editorElement, {
        image: {
            resizeUnit: 'px',
            resizeOptions: [
                {
                    name: 'resizeImage:original',
                    label: 'Original',
                    value: null
                },
                {
                    name: 'resizeImage:100',
                    label: '100px',
                    value: '100'
                },
                {
                    name: 'resizeImage:200',
                    label: '200px',
                    value: '200'
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

The following demo uses CSS to set up the fixed image aspect ratio, so a 200px wide image automatically gets the same height.

.ck.ck-content .image {
    position: relative;
}
.ck.ck-content .image img {
    position: absolute;
    left: 0;
    top: 0;
    width: 100%;
    height: 100%;
    object-fit: cover;
    border-radius: 50%;
}
.ck.ck-content .image::before {
    content: '';
    padding-top: 100%;
    display: block;
}

Check out the difference in the live demo below:

Poppies on the Wheat

Helen Hunt Jackson

Along Ancona's hills the shimmering heat,
A tropic tide of air with ebb and flow
Bathes all the fields of wheat until they glow
Like flashing seas of green, which toss and beat
Around the vines. The poppies lithe and fleet
Seem running, fiery torchmen, to and fro
To mark the shore.

The farmer does not know
That they are there. He walks with heavy feet,
Counting the bread and wine by autumn's gain,
But I,—I smile to think that days remain
Perhaps to me in which, though bread be sweet
No more, and red wine warm my blood in vain,
I shall be glad remembering how the fleet,
Lithe poppies ran like torchmen with the wheat.

# Image optimization and responsive images

When using the CKBox file manager service, it produces sets of resized, optimized images. The users can invoke these resized versions if needed. To learn more about these capabilities, refer to the responsive images guide and the CKBox conversion guide.

# Installation

The image resize feature is enabled by default in the document editor build only.

To enable it in other editor builds, install the ImageResize plugin, which contains all needed features (ImageResizeEditing, ImageResizeHandles, ImageResizeButtons):

import { Image, ImageResize } from '@ckeditor/ckeditor5-image';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image, ImageResize, /* ... */ ],
        // More of editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Common API

The ImageResize plugin registers:

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 at https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image.