indent.md 5.4 KB


title: Block indentation

category: features

{@snippet features/build-indent-source}

Demo

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

{@snippet features/indent}

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 {@link features/indent#demo 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%;
	}

{@snippet features/custom-indent-block-classes}

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 {@link module:indent/indent~Indent} plugin, but neither those buttons nor respective commands implement any functionality by default.

The target behavior comes in two other plugins:

  • {@link module:indent/indentblock~IndentBlock} — The indent block feature controls the indentation of elements such as paragraphs and headings.
  • {@link module:list/list~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 {@link builds/guides/integration/installing-plugins installing plugins}.

Common API

The {@link module:indent/indent~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 {@link module:indent/indentblock~IndentBlock} plugin registers the following components:

  • The {@link module:indent/indentblockcommand~IndentBlockCommand 'indentBlock'} command.

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

    editor.execute( 'indentBlock' );
    
  • The {@link module:indent/indentblockcommand~IndentBlockCommand '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 {@link framework/guides/development-tools#ckeditor-5-inspector 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.