--- category: features --- # Headings {@snippet build-classic-source} The {@link module:heading/heading~Heading} feature enables support for headings. 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 page's main title and the page content will usually start from `

`. Additionally, the `

` element is supported when pasting into the editor and is converted to `

` ("Heading 1") by default. You can read more about why the editor should not create `

` elements in the [Headings section of Editor Recommendations](http://ckeditor.github.io/editor-recommendations/features/headings.html). ### 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 {@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

Heading 1

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' } ] } } ) .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} ## 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( ... ); ``` 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 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' } ); ``` We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector instance 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-heading.