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

guideBlock toolbar

The block toolbar plugin provides an additional configurable toolbar on the left-hand side of the content area. The block toolbar comes in handy when you cannot access the main editor toolbar.

# Demo

In the editor below, move the caret around the content. You will see that the block toolbar button drag indicator is following your selection. Click the button to show the toolbar.

The great things you learn from traveling

Three Monks walking on ancient temple.

Like all the great things on earth traveling teaches us by example. Here are some of the most precious lessons I’ve learned over the years of traveling.

Appreciation of diversity

Getting used to an entirely different culture can be challenging. While it’s also nice to learn about cultures online or from books, nothing comes close to experiencing cultural diversity in person. You learn to appreciate each and every single one of the differences while you become more culturally fluid.

This demo presents a limited set of features. Visit the feature-rich editor example to see more in action.

# Additional feature information

To access the block toolbar, you need to click the button with braille pattern dots icon drag indicator on the left-hand side of the content area (the gutter). The button appears next to the selected block element (for example, a paragraph), following the caret as the user edits the content and navigates the document.

The icon drag indicator is also a handle to drag blocks of content around the editor. Click a heading in the demo above and drag it all the way down between the following paragraphs to see this functionality in action.

The block toolbar complements the balloon editor where it falls short, for example when you must insert some content (like an image), but the selection is collapsed, so you cannot access the toolbar. You can read more about it in the balloon block editor overview.

See the balloon block editor example page, too.

# Configuration

The content of the toolbar can be defined using the blockToolbar configuration. See the installation instructions to learn more.

Because the toolbar is always connected to the block of content, it works best with the features that modify entire blocks (for example, create headings) or insert objects (like images or tables) rather than inline styles (like bold or italic).

To adjust the position of the block toolbar button to match the styles of your website, use the CSS transform property:

.ck.ck-block-toolbar-button {
    transform: translateX( -10px );
}

If you plan to run the editor in a right–to–left (RTL) language, keep in mind the button will be attached to the right boundary of the editable area. In that case, make sure the CSS position adjustment works properly by adding the following styles:

.ck[dir="rtl"] .ck-block-toolbar-button {
    transform: translateX( 10px );
}

Before the v40.0.0 release of CKEditor 5, the block toolbar used the pilcrow icon (¶) as a handle. This was changed to braille pattern dots icon Drag indicator as a default. If you want to use a different icon, you can configure it easily, for example:

    blockToolbar: {
        items: [
            'bold',
            'italic',
            'link'
        ],
        icon: 'pilcrow' // or SVG.
    },

# Installation

Remember to add relevant features to the editor configuration first. The block toolbar provides a space for the buttons, but it does not bring the actual features. For example, the heading1 button will not work if there is no Headings feature in the editor.

To add this feature to your editor install the @ckeditor/ckeditor5-ui package:

npm install --save @ckeditor/ckeditor5-ui

Add the BlockToolbar to your plugin list and configure the feature using the blockToolbar property:

import { BlockToolbar } from '@ckeditor/ckeditor5-ui';
import { HeadingButtonsUI } from '@ckeditor/ckeditor5-heading';
import { ParagraphButtonUI } from '@ckeditor/ckeditor5-paragraph';

BalloonEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ BlockToolbar, ParagraphButtonUI, HeadingButtonsUI, /* ... */ ],
        blockToolbar: [
            'paragraph', 'heading1', 'heading2', 'heading3',
            '|',
            'bulletedList', 'numberedList',
            '|',
            'blockQuote', 'uploadImage'
        ],
        toolbar: [ /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

You can also use the shouldNotGroupWhenFull option to prevent automatic items grouping in the block toolbar:

import { BlockToolbar } from '@ckeditor/ckeditor5-ui';
import { HeadingButtonsUI } from '@ckeditor/ckeditor5-heading';
import { ParagraphButtonUI } from '@ckeditor/ckeditor5-paragraph';

BalloonEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ BlockToolbar, ParagraphButtonUI, HeadingButtonsUI, /* ... */ ],
        blockToolbar: {
            items: [
                'paragraph', 'heading1', 'heading2', 'heading3',
                '|',
                'bulletedList', 'numberedList',
                '|',
                'blockQuote', 'uploadImage'
            ],
            shouldNotGroupWhenFull: true
        },
        toolbar: [ /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

You can also change the current default toolbar icon 'dragIndicator' Drag indicator by choosing predefined icon from list using option icon or by passing a SVG string:

import { BlockToolbar } from '@ckeditor/ckeditor5-ui';
import { HeadingButtonsUI } from '@ckeditor/ckeditor5-heading';
import { ParagraphButtonUI } from '@ckeditor/ckeditor5-paragraph';

BalloonEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ BlockToolbar, ParagraphButtonUI, HeadingButtonsUI, /* ... */ ],
        blockToolbar: {
            items: [
                'paragraph', 'heading1', 'heading2', 'heading3',
                '|',
                'bulletedList', 'numberedList',
                '|',
                'blockQuote', 'uploadImage'
            ],
            icon: 'pilcrow'
            // or
            // icon: '<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24">' +
            //		'<path d="M120-240v-80h720v80H120Zm0-200v-80h720v80H120Zm0-200v-80h720v80H120Z"/></svg>'
        },
        toolbar: [ /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

Read more about installing plugins.

# Contribute

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