title: Block indentation
{@snippet features/build-indent-source}
The indentation feature allows to set indentation of text blocks like paragraphs or headings and lists.
{@snippet features/indent}
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( ... );
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}
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:
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.
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}.
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.
The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-font.