CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Interface

HeadingConfig (heading)

@ckeditor/ckeditor5-heading/src/headingconfig

interface
See source

The configuration of the heading feature. The option is used by the HeadingEditing feature.

ClassicEditor
  .create( {
    heading: ... // Heading feature config.
  } )
  .then( ... )
  .catch( ... );

See all editor options.

Filtering

Properties

  • options : Array<HeadingOption> | undefined

    See source

    The available heading options.

    The default value is:

    const headingConfig = {
  options: [
    { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
    { model: 'heading1', view: 'h2', title: 'Heading 1', class: 'ck-heading_heading1' },
    { model: 'heading2', view: 'h3', title: 'Heading 2', class: 'ck-heading_heading2' },
    { model: 'heading3', view: 'h4', title: 'Heading 3', class: 'ck-heading_heading3' }
  ]
};

    It defines 3 levels of headings. In the editor model they will use heading1, heading2, and heading3 elements. Their respective view elements (so the elements output by the editor) will be: h2, h3, and h4. This means that if you choose "Heading 1" in the headings dropdown the editor will turn the current block to <heading1> in the model which will result in rendering (and outputting to data) the <h2> element.

    The title and class properties will be used by the headings dropdown to render available options. Usually, the first option in the headings dropdown is the "Paragraph" option, hence it's also defined on the list. However, you don't need to define its view representation because it's handled by the Paragraph feature (which is required by the HeadingEditing feature).

    You can read more about configuring heading levels and see more examples in the Headings guide.

    Note: In the model you should always start from heading1, regardless of how the headings are represented in the view. That's assumption is used by features like Autoformat to know which element they should use when applying the first level heading.

    The defined headings are also available as values passed to the 'heading' command under their model names. For example, the below code will apply <heading1> to the current selection:

    editor.execute( 'heading', { value: 'heading1' } );