Headings

The Heading feature enables support for headings.

# 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 build does not include the title plugin, a <h1> element pasted into the rich-text editor is converted to <h2> (“Heading 1”).

# Configuring heading levels

It is, of course, possible to configure which heading levels the editor should 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-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( ... );

# Installation

To add this feature to your editor install the @ckeditor/ckeditor5-heading package:

npm install --save @ckeditor/ckeditor5-heading

And add it to your plugin list and toolbar configuration:

import Heading from '@ckeditor/ckeditor5-heading/src/heading';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Heading, ... ],
        toolbar: [ 'heading', ... ]
    } )
    .then( ... )
    .catch( ... );

# Common API

The Heading plugin registers:

• The 'heading' dropdown.

• The 'heading' command that accepts 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' } );
  

# Contribute

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