Headings
The heading feature helps you structure your document by adding headings to parts of the text. They make your content easier to scan by both readers and search engines.
# Demo
Use the toolbar dropdown to style a heading. You can also type one or more #
characters (depending on the heading level) followed by a space, and the autoformatting feature will create a new heading.
On the importance of headings
What is a heading?
A heading is a title or a subtitle displayed in a document or webpage. Headings are created with the <h1> to <h6> HTML tags where <h1> is the main heading and <h6> is the lowest level heading.
Why use headings
Headings in a document serve a dual purpose: they help the creators and readers interact with the content and affect the way search engines index the webpage.
Human interaction
Having a clearly defined structure with sections and subsections is beneficial for both the creator and the readers. The creator can convey their message better and emphasize important parts. A few informative headings can help the readers scan the document in search for specific information.
Search engine indexing algorithms
Search engines use the headings to index the structure of the document and point to important keywords.
This demo presents a limited set of features. Visit the feature-rich editor example to see more in action.
# Heading levels
By default, this feature is configured to support <h2>
, <h3>
, and <h4>
elements which are named: “Heading 1,” “Heading 2,” and “Heading 3,” respectively. The rationale behind starting from <h2>
is that <h1>
should be reserved for the page’s main title and the page content will usually start from <h2>
.
Support for adding a document title is provided through the Title
plugin. When it is enabled, a <h1>
element pasted into the editor will be rendered as the document title.
By default, when your editor preset does not include the title plugin, an <h1>
element pasted into the rich-text editor is converted to <h2>
(“Heading 1”).
You can read more about why the editor should not create <h1>
elements for content headings in the Headings section of Editor Recommendations.
# 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.
Choosing the best user experience
Usability
Different situations may require different solutions. Splitting the heading dropdown into separate buttons gives the user quicker access, but at the same time takes up more space. It is up to you to decide whether easier accessibility is more important than a tidy toolbar.
Personal preference
Usability and editing needs are not the only factors. Sometimes the user’s personal preference and previous experience are equally important.
Flexibility
Whichever you choose, CKEditor 5 offers both the standard heading dropdown list and separate heading toolbar buttons. This way you can meet your users’ individual needs.
# 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, Heading } from 'ckeditor5';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ Heading, /* ... */ ],
toolbar: [ 'heading', /* ... */ ]
} )
.then( /* ... */ )
.catch( /* ... */ );
# Installation with toolbar heading buttons
To configure the toolbar buttons for styling text as headings and paragraphs, you need to import the following into your plugin list and configuration:
import { ClassicEditor, HeadingButtonsUI, ParagraphButtonUI } from 'ckeditor5';
# 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 heading.options
configuration option to do so.
For example, the following editor will support only two levels of headings – <h1>
and <h2>
:
<div id="editor">
<h1>Heading 1</h1>
<h2>Heading 2</h2>
<p>This is <a href="https://ckeditor.com">CKEditor 5</a>.</p>
</div>
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( /* ... */ );
# Configuring custom heading elements
It is also possible to define fully custom elements for headings by using the advanced format of the heading.options
configuration option.
For example, the following editor will support the following two heading options at the same time: <h2 class="fancy">
and <h2>
:
<style>
/* Styles for the heading in the content and for the dropdown item. */
h2.fancy, .ck.ck-button.ck-heading_heading2_fancy {
color: #ff0050;
font-size: 17px;
}
</style>
<div id="snippet-custom-heading-levels">
<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h2 class="fancy">Fancy Heading 2</h2>
<p>This is <a href="https://ckeditor.com">CKEditor 5</a>.</p>
</div>
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( /* ... */ );
# Configuring toolbar buttons
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 for instructions on how to do it.
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( /* ... */ );
# Related features
There are more CKEditor 5 features that can help you format your content:
- Basic text styles – The essentials, like bold, italic, and others.
- Document title – Clearly divide your content into a title and body.
- Block indentation – Set indentation for text blocks such as paragraphs or lists.
- Lists – Organize your content better with ordered and unordered lists you can style.
- Remove format – Easily clean basic text formatting.
- Autoformatting – Add formatting elements (such as headings) as you type with Markdown code.
# Common API
The Heading
plugin registers:
-
The
'heading'
dropdown. -
The
'heading'
command that accepts a value based on theheading.options
configuration option.You can turn the currently selected block(s) to headings by executing one of these commands:
editor.execute( 'heading', { value: 'heading2' } );
The 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 ParagraphButtonUI
plugin registers the UI button component: 'paragraph'
.
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 at https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-heading.
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.