Contribute to this guideReport an issue

guideBlock indentation

# Demo

The indentation feature allows to set indentation of text blocks like paragraphs or headings and lists.

Changing block indentation

Use the toolbar buttons to control the indentation of specific parts of the text. You can use these tools to highlight an important piece of information, communicate a hierarchy or just give your content some room. 

For instance, this paragraph looks like it belongs to the previous one.

Indenting list items

Block indentation buttons work with lists too! Check out the following list and play with different indentation levels:

  • This is the shallowest list item. 
    • And this one is nested.
    • This one is nested too.
      • And this one goes even deeper.

# Configuring the block indentation feature

# Using offset and unit

By default, the block indentation feature increases or decreases the current indentation by the given offset, using the given unit.

The editor used in the demo section above uses the default configuration, which defines a 40px indentation step.

You can change that value to, for example, 1em:

import Indent from '@ckeditor/ckeditor5-indent/src/indent';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Indent, ... ],
        toolbar: {
            items: [ 'heading', '|', 'outdent', 'indent', '|', 'bulletedList', 'numberedList', '|', 'undo', 'redo' ]
        },
        indentBlock: {
            offset: 1,
            unit: 'em'
        }
    } )
    .then( ... )
    .catch( ... );

# Using CSS classes

Alternatively, the block indentation feature can be configured to set indentation by applying one of defined CSS classes:

import Indent from '@ckeditor/ckeditor5-indent/src/indent';
import IndentBlock from '@ckeditor/ckeditor5-indent/src/indentblock';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Indent, IndentBlock, ... ],
        toolbar: {
            items: [ 'heading', '|', 'outdent', 'indent', '|', 'bulletedList', 'numberedList', '|', 'undo', 'redo' ]
        },
        indentBlock: {
            classes: [
                'custom-block-indent-a', // First step - smallest indentation.
                'custom-block-indent-b',
                'custom-block-indent-c',
                'custom-block-indent-d',
                'custom-block-indent-e'  // Last step - biggest indentation.
            ]
        }
    } )
    .then( ... )
    .catch( ... );

The editor will restrict indentation levels to a set of provided classes. The biggest indentation is the class that has last index in the array.

In the demo below the CSS classes are defined as follows:

.custom-block-indent-a {
    margin-left: 10%;
}

.custom-block-indent-b {
    margin-left: 20%;
}

.custom-block-indent-c {
    margin-left: 30%;
}

.custom-block-indent-d {
    margin-left: 40%;
}

.custom-block-indent-e {
    margin-left: 50%;
}

Block indentation using CSS classes

If you want more semantics in your content, use CSS classes instead of fixed indentation units. You can then adjust the levels in the styles sheets of your application whenever you want. 

This heading has the .custom-block-indent-a class

And this paragraph shares the same class, and that puts it at the same level.

But this one has the .custom-block-indent-b class

Using classes instead of fixed units (px or em) has another advantage. You retain control over what indentation levels are used in the documents. For instance, you can limit indentation to 2 or 3 different levels and there is no way users can go beyond that (.custom-block-indent-e class level). That should help you keep your content clean and predictable.

# Indenting lists

The same set of buttons (outdent, indent), besides controlling block indentation, allows indenting list items (nesting them). This is completely transparent to the user.

From the code perspective, the buttons are implemented by the Indent plugin, but neither those buttons nor respective commands implement any functionality by default.

The target behavior comes in two other plugins:

  • IndentBlock — The indent block feature controls the indentation of elements such as paragraphs and headings.
  • List — The list feature implements the indentation (nesting) of lists.

This means, that if you want to allow indenting lists only, you can do that by load only the Indent and List plugins. If you want the full behavior, you need to load all 3 plugins.

# Installation

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

npm install --save @ckeditor/ckeditor5-indent

Then add it to your plugin list and the toolbar configuration:

import Indent from '@ckeditor/ckeditor5-indent/src/indent';
import IndentBlock from '@ckeditor/ckeditor5-indent/src/indentblock';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Indent, IndentBlock, ... ],
        toolbar: [ 'outdent', 'indent', ... ]
    } )
    .then( ... )
    .catch( ... );

Read more about installing plugins.

# Common API

The Indent plugin registers the following components:

  • The 'indent' command.

    Note, this command does not implement any behavior itself. It executes either indentBlock (described below) or indentList, depending on which of these commands is enabled.

    Read more in the Indenting lists section above.

  • The 'outdent' command.

    Note, this command does not implement any behavior itself. It executes either outdentBlock (described below) or outdentList, depending on which of these commands is enabled.

    Read more in the Indenting lists section above.

The IndentBlock plugin registers the following components:

  • The 'indentBlock' command.

    You can increase the indentation of the block in which the selection is set by:

    editor.execute( 'indentBlock' );
    
  • The 'outdentBlock' command.

    You can decrease the indentation of the block in which the selection is set by:

    editor.execute( 'outdentBlock' );
    

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