or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

command-system.mdconfiguration.mdcore-plugin.mddocument-structure.mdediting-engine.mdindex.mdui-components.md
tile.json

ui-components.mddocs/

UI Components

User interface components for heading functionality including dropdown selectors and individual heading buttons. These components provide different ways for users to apply heading formats in the editor.

Capabilities

HeadingUI Plugin

Provides the main heading dropdown component and menu bar integration for selecting heading levels.

/**
 * The headings UI feature. Introduces the headings dropdown and menu bar components.
 */
class HeadingUI extends Plugin {
    /** Plugin name identifier */
    static readonly pluginName: 'HeadingUI';
    
    /** Indicates this is an official CKEditor 5 plugin */
    static readonly isOfficialPlugin: true;
    
    /**
     * Registers 'heading' and 'menuBar:heading' UI components.
     * Creates dropdown component for toolbar and menu bar integration.
     */
    init(): void;
}

Usage Examples:

import { HeadingUI } from '@ckeditor/ckeditor5-heading';

// Add heading dropdown to toolbar
ClassicEditor.create(document.querySelector('#editor'), {
    plugins: [HeadingUI, /* other plugins */],
    toolbar: ['heading', /* other tools */]
});

// Add heading to menu bar
ClassicEditor.create(document.querySelector('#editor'), {
    plugins: [HeadingUI, /* other plugins */],
    menuBar: {
        items: ['menuBar:heading', /* other items */]
    }
});

HeadingButtonsUI Plugin

Provides individual button components for each heading level as an alternative to the dropdown interface.

/**
 * Defines UI buttons for individual heading levels as an alternative to dropdown.
 */
class HeadingButtonsUI extends Plugin {
    /**
     * Creates individual button components for each heading option.
     * Registers separate toolbar buttons for each configured heading level.
     */
    init(): void;
}

Usage Examples:

import { HeadingButtonsUI } from '@ckeditor/ckeditor5-heading';

// Use individual heading buttons instead of dropdown
ClassicEditor.create(document.querySelector('#editor'), {
    plugins: [HeadingButtonsUI, /* other plugins */],
    toolbar: [
        'heading1', 'heading2', 'heading3', // Individual buttons
        'paragraph', // Paragraph button
        /* other tools */
    ]
});

// Custom heading configuration with icons for buttons
ClassicEditor.create(document.querySelector('#editor'), {
    plugins: [HeadingButtonsUI, /* other plugins */],
    toolbar: ['heading1', 'heading2', 'customHeading'],
    heading: {
        options: [
            { 
                model: 'heading1', 
                view: 'h2', 
                title: 'Heading 1', 
                class: 'ck-heading_heading1',
                icon: '<svg>...</svg>' // Custom icon for button
            },
            { 
                model: 'heading2', 
                view: 'h3', 
                title: 'Heading 2', 
                class: 'ck-heading_heading2',
                icon: 'heading2' // Built-in icon name
            },
            {
                model: 'customHeading',
                view: { name: 'h4', classes: 'custom' },
                title: 'Custom Heading',
                class: 'ck-heading_custom',
                icon: 'heading3'
            }
        ]
    }
});

UI Component Registration

Both UI plugins register components that can be used in different parts of the editor interface:

HeadingUI Components:

  • 'heading' - Dropdown component for toolbar
  • 'menuBar:heading' - Menu bar item for heading selection

HeadingButtonsUI Components:

  • Individual buttons based on heading options (e.g., 'heading1', 'heading2', 'paragraph')
  • Button names correspond to the model property of each heading option

Dropdown Component Behavior

The heading dropdown shows all configured heading options with:

  • Visual preview: Each option displays with its actual styling
  • Current state: Shows the currently active heading level
  • Title text: User-friendly names for each option
  • CSS classes: Custom styling via the class property
// Example dropdown options display:
// ┌─────────────────────┐
// │ ○ Paragraph         │
// │ ● Heading 1         │  ← Currently selected
// │ ○ Heading 2         │
// │ ○ Heading 3         │
// └─────────────────────┘

Button Component Behavior

Individual heading buttons provide:

  • Toggle state: Active when the current selection matches the button's heading level
  • Icons: Optional custom icons via the icon property
  • Tooltips: Display the heading title on hover
  • Keyboard shortcuts: Support for keyboard activation
// Example toolbar with individual buttons:
// [H1] [H2] [H3] [P] | Bold | Italic | ...
//  ●    ○    ○   ○     ← H1 is currently active

Accessibility Features

Both UI components include accessibility support:

  • ARIA labels: Descriptive labels for screen readers
  • Keyboard navigation: Full keyboard support for component interaction
  • Focus management: Proper focus handling for dropdown and buttons
  • State announcements: Screen reader announcements for heading level changes

Localization Support

UI components support internationalization through CKEditor 5's translation system:

// Heading titles can be localized
const config = {
    heading: {
        options: [
            { model: 'paragraph', title: t('Paragraph'), class: 'ck-heading_paragraph' },
            { model: 'heading1', view: 'h2', title: t('Heading 1'), class: 'ck-heading_heading1' }
        ]
    }
};

The plugin automatically uses localized strings for default heading options when available in the editor's language pack.