Block indentation

The block indentation feature lets you set indentation for text blocks such as paragraphs, headings, or lists. This way you can visually distinguish parts of your content.

# Demo

Use the indent or outdent toolbar buttons in the editor below to change the indentation level. Try this on different elements: paragraphs, headings, and list items.

Changing block indentation

Use the toolbar buttons to change the indentation of different parts of the text. This way you can highlight an important point, show a hierarchy of information, or just give your content some room to breathe.

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.

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

    # Installation

    ⚠️ New import paths

    Starting with version 42.0.0, we changed the format of import paths. This guide uses the new, shorter format. Refer to the Packages in the legacy setup guide if you use an older version of CKEditor 5.

    After installing the editor, add the feature to your plugin list and toolbar configuration:

    import < ClassicEditor, Indent, IndentBlock >from 'ckeditor5'; ClassicEditor .create( document.querySelector( '#editor' ), < plugins: [ Indent, IndentBlock, /* . */ ], toolbar: [ 'outdent', 'indent', /* . */ ] >) .then( /* . */ ) .catch( /* . */ ); 

    # Configuring the block indentation feature

    This feature offers a few configuration options that can be used to adjust the text block indentation behavior. It is implemented by three plugins: Indent , IndentBlock and List .

    # 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 rich-text editor from the demo section above uses the default configuration, which defines a 40px indentation step.

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

    import < ClassicEditor, Indent >from 'ckeditor5'; 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

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

    Here is how you can configure the block indentation feature to set indentation by applying one of the defined CSS classes:

    import < ClassicEditor, Indent, IndentBlock >from 'ckeditor5'; 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' // Last step - biggest indentation. ] >> ) .then( /* . */ ) .catch( /* . */ ); 

    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 the users can go beyond that. In the example above, the .custom-block-indent-c class level is the maximum allowed indentation value. This should help keep your content clean and predictable.

    In this configuration, the WYSIWYG editor will restrict indentation levels to the set of provided classes. The class with the last index in the array has the biggest indentation.

    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

    Note that for RTL content, 'margin-right' should be used instead. Learn more about configuring language of the editor content.

    Block indentation using CSS classes

    This is a normal paragraph with no indentation applied.

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

    This paragraph has the same class as the heading above, so they’re both at the same level.

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

    This paragraph has the same indentation class as the heading above.

    This paragraph has the .custom-block-indent-c class. This is the maximum indentation level allowed in the configuration.

    # Indenting lists

    Besides controlling text block indentation, the same set of buttons ( outdent , indent ) allows for indenting list items (nesting them).

    This mechanism is completely transparent to the user. From the code perspective, the buttons are implemented by the Indent plugin, but neither these buttons nor the respective commands implement any functionality by default.

    The target behavior comes from 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 loading only the Indent and List plugins. If you want the full behavior, you need to load all 3 plugins ( Indent , IndentBlock , and List ).

    # Related features

    Here are some CKEditor 5 features that may help structure your content better:

    • Block quote – Include block quotations or pull quotes in your rich-text content.
    • Headings – Divide your content into sections.
    • Code block – Insert longer, multiline code listings.
    • Text alignment – Because it does matter whether the content is left, right, centered, or justified.

    Block indentation can be removed with the remove format feature.

    # Common API

    The Indent plugin registers the following components:

    • The 'indent' command. This command does not implement any indentation behavior by 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. This command does not implement any indentation behavior by 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 text block that contains the selection by:

    editor.execute( 'indentBlock' ); 

    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

    Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.

    With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.

    © 2003-2024 CKSource. All rights reserved.