---
category: features
---
# Headings
{@snippet features/heading-source}
The {@link module:heading/heading~Heading} feature enables support for headings. These are used by the creators to structure their documents. They also aid both the readers, making the content more organized and easier to read, and the search indexers scanning for crucial information.
Headings can easily be added with toolbar dropdown, buttons or with {@link features/autoformat Markdown code} as you type. They can also be cleared with the {@link features/remove-format remove format} feature.
This feature is enabled by default in all builds.
## Heading levels
By default this feature is configured to support `
`, `` and `` elements which are named: "Heading 1", "Heading 2" and "Heading 3", respectively. The rationale behind starting from `` is that `` should be reserved for the {@link features/title page's main title} and the page content will usually start from ``.
Support for adding a document title is provided through the {@link module:heading/title~Title} plugin. This plugin is optional and needs to be {@link builds/guides/integration/installing-plugins added to your editor build}. When it is enabled, a `` element pasted into the editor will be rendered as the {@link features/title document title}.
By default, when your editor build does not include the title plugin, a `` element pasted into the rich-text editor is converted to `` ("Heading 1").
You can read more about why the editor should not create `` elements for content headings in the [Headings section of Editor Recommendations](http://ckeditor.github.io/editor-recommendations/features/headings.html).
## Demo
Use the toolbar dropdown to style a heading, or type one or more `#` characters (depending on the heading level), followed by a space, to start a new heading with the {@link features/autoformat autoformatting feature}.
{@snippet features/default-headings}
## Heading buttons
The heading feature lets you also use a set of heading buttons instead of the dropdown list. The toolbar buttons are configurable and it is possible to include a paragraph button, too. Compare the heading toolbar dropdown from the demo above with the heading buttons below to check the functionality and usability of this variation.
{@snippet features/heading-buttons}
## Related features
There are more CKEditor 5 features that can help you format your content:
* {@link features/basic-styles Basic font styles} – The essentials, like **bold**, *italic* and others.
* {@link features/title Document title} – Clearly divide your content into a title and body.
* {@link features/indent Block indentation} – Set indentation for text blocks such as paragraphs or lists.
* {@link features/lists Lists} – Organize your content better with ordered and unordered lists you can style.
* {@link features/remove-format Remove format} – Easily clean basic text formatting.
* {@link features/autoformat Autoformatting} – Add formatting elements (such as headings) as you type with Markdown code.
## Configuration
### Configuring heading levels
You can configure which heading levels the editor will support and how they should be named in the Headings dropdown. Use the {@link module:heading/heading~HeadingConfig#options `heading.options`} configuration option to do so.
For example, the following editor will support only two levels of headings — `` and ``:
```html
```
```js
ClassicEditor
.create( document.querySelector( '#editor' ), {
heading: {
options: [
{ model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
{ model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
{ model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' }
]
}
} )
.then( ... )
.catch( ... );
```
{@snippet features/custom-heading-levels}
### Configuring custom heading elements
It is also possible to define fully custom elements for headings by using the {@link module:engine/conversion/conversion~ConverterDefinition advanced format} of the {@link module:heading/heading~HeadingConfig#options `heading.options`} configuration option.
For example, the following editor will support the following two heading options at the same time: `` and ``:
```html
Heading 1
Heading 2
Fancy Heading 2
This is CKEditor 5.
```
```js
ClassicEditor
.create( document.querySelector( '#editor' ), {
heading: {
options: [
{ model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
{ model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
{ model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
{
model: 'headingFancy',
view: {
name: 'h2',
classes: 'fancy'
},
title: 'Heading 2 (fancy)',
class: 'ck-heading_heading2_fancy',
// It needs to be converted before the standard 'heading2'.
converterPriority: 'high'
}
]
}
} )
.then( ... )
.catch( ... );
```
{@snippet features/custom-heading-elements}
### Configuring toolbar buttons
In order to use individual toolbar buttons instead of the heading dropdown, you need to properly configure the feature. You also need to import proper UI elements; see the [installation section](#installation-with-toolbar-heading-buttons) for instructions on how to do it.
```js
ClassicEditor
.create( document.querySelector( '#editor' ), {
toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3', 'heading4', 'heading5', 'heading6', '|', 'undo', 'redo' ],
heading: {
options: [
{ model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
{ model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
{ model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
{ model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
{ model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
{ model: 'heading5', view: 'h5', title: 'Heading 5', class: 'ck-heading_heading5' },
{ model: 'heading6', view: 'h6', title: 'Heading 6', class: 'ck-heading_heading6' }
]
}
} )
.then( ... )
.catch( ... );
```
{@snippet features/custom-heading-buttons}
## Installation
This feature is enabled by default in all builds. The installation instructions are for developers interested in building their own, custom editor.
To add this feature to your editor install the [`@ckeditor/ckeditor5-heading`](https://www.npmjs.com/package/@ckeditor/ckeditor5-heading) package:
```
npm install --save @ckeditor/ckeditor5-heading
```
And add it to your plugin list and toolbar configuration:
```js
import Heading from '@ckeditor/ckeditor5-heading/src/heading';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ Heading, ... ],
toolbar: [ 'heading', ... ]
} )
.then( ... )
.catch( ... );
```
### Installation with toolbar heading buttons
In order to be able to configure the toolbar buttons for headings and paragraph, you need to import the following into your plugin list and configuration:
```js
import HeadingButtonsUI from '@ckeditor/ckeditor5-heading/src/headingbuttonsui';
import ParagraphButtonUI from '@ckeditor/ckeditor5-paragraph/src/paragraphbuttonui';
```
Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
## Common API
The {@link module:heading/heading~Heading} plugin registers:
* The `'heading'` dropdown.
* The `'heading'` command that accepts a value based on the {@link module:heading/heading~HeadingConfig#options `heading.options`} configuration option.
You can turn the currently selected block(s) to headings by executing one of these commands:
```js
editor.execute( 'heading', { value: 'heading2' } );
```
The {@link module:heading/headingbuttonsui~HeadingButtonsUI} plugin registers six UI button components that will execute the `'heading'` command with the proper value of the `value` attribute:
* `'heading1'`
* `'heading2'`
* `'heading3'`
* `'heading4'`
* `'heading5'`
* `'heading6'`
The {@link module:paragraph/paragraphbuttonui~ParagraphButtonUI} plugin registers the UI button component: `'paragraph'`.
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/tree/master/packages/ckeditor5-heading.