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.

# 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>.

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”).

# 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.

# Installation

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

import { ClassicEditor, Heading } from 'ckeditor5';

ClassicEditor
	.create( document.querySelector( '#editor' ), {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ Heading, /* ... */ ],
		toolbar: [ 'heading', /* ... */ ]
		heading: {
			// Configuration.
		}
	} )
	.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&nbsp;5</a>.</p>
</div>

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        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&nbsp;5</a>.</p>
</div>

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        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' ), {
        // ... Other configuration options ...
        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 the heading.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'.

# Contribute

The source code of the feature is available on GitHub at https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-heading.