or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

CKEditor 5 Basic Styles

CKEditor 5 Basic Styles provides essential text formatting features for CKEditor 5, enabling users to apply bold, italic, underline, strikethrough, subscript, superscript, and code styling to text content. Each feature is implemented as a CKEditor 5 plugin that integrates seamlessly with the editor's architecture, providing UI buttons, keyboard shortcuts, and programmatic access through commands.

Package Information

  • Package Name: @ckeditor/ckeditor5-basic-styles
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ckeditor/ckeditor5-basic-styles (typically included in main ckeditor5 package)

Core Imports

import { 
  Bold, Italic, Code, Strikethrough, Subscript, Superscript, Underline,
  BoldEditing, ItalicEditing, CodeEditing, StrikethroughEditing, 
  SubscriptEditing, SuperscriptEditing, UnderlineEditing,
  BoldUI, ItalicUI, CodeUI, StrikethroughUI, 
  SubscriptUI, SuperscriptUI, UnderlineUI,
  AttributeCommand,
  _getBasicStylesButtonCreator
} from "@ckeditor/ckeditor5-basic-styles";

For CommonJS:

const { 
  Bold, Italic, Code, Strikethrough, Subscript, Superscript, Underline,
  AttributeCommand
} = require("@ckeditor/ckeditor5-basic-styles");

To access icons for custom UI implementations:

import { IconBold, IconItalic, IconCode } from '@ckeditor/ckeditor5-icons';

Basic Usage

import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';
import { Bold, Italic, Code, Underline } from '@ckeditor/ckeditor5-basic-styles';

ClassicEditor
  .create(document.querySelector('#editor'), {
    plugins: [Bold, Italic, Code, Underline],
    toolbar: ['bold', 'italic', 'code', 'underline']
  })
  .then(editor => {
    // Execute formatting commands programmatically
    editor.execute('bold');
    editor.execute('italic');
    
    // Check command state
    const boldCommand = editor.commands.get('bold');
    console.log('Is bold active:', boldCommand.value);
    console.log('Is bold enabled:', boldCommand.isEnabled);
  });

Architecture

CKEditor 5 Basic Styles follows a consistent plugin architecture pattern:

  • Main Feature Plugins: Complete plugins that combine editing and UI functionality (e.g., Bold, Italic)
  • Editing Plugins: Handle model attributes, schema, conversion, and commands (e.g., BoldEditing, ItalicEditing)
  • UI Plugins: Provide toolbar buttons and menu items (e.g., BoldUI, ItalicUI)
  • Command System: All features use AttributeCommand for consistent toggle behavior
  • Keyboard Shortcuts: Built-in shortcuts (Ctrl+B for bold, Ctrl+I for italic)
  • Two-Step Caret Movement: Code feature includes special caret navigation for inline code elements

Capabilities

Main Feature Plugins

Complete plugins that provide both editing and UI functionality for text formatting.

/**
 * Complete bold formatting feature combining editing and UI
 */
class Bold extends Plugin {
  static get requires(): readonly [typeof BoldEditing, typeof BoldUI];
  static get pluginName(): "Bold";
  static get isOfficialPlugin(): true;
}

/**
 * Complete italic formatting feature combining editing and UI
 */
class Italic extends Plugin {
  static get requires(): readonly [typeof ItalicEditing, typeof ItalicUI];
  static get pluginName(): "Italic";
  static get isOfficialPlugin(): true;
}

/**
 * Complete inline code formatting feature combining editing and UI
 */
class Code extends Plugin {
  static get requires(): readonly [typeof CodeEditing, typeof CodeUI];
  static get pluginName(): "Code";
  static get isOfficialPlugin(): true;
}

/**
 * Complete strikethrough formatting feature combining editing and UI
 */
class Strikethrough extends Plugin {
  static get requires(): readonly [typeof StrikethroughEditing, typeof StrikethroughUI];
  static get pluginName(): "Strikethrough";
  static get isOfficialPlugin(): true;
}

/**
 * Complete subscript formatting feature combining editing and UI
 */
class Subscript extends Plugin {
  static get requires(): readonly [typeof SubscriptEditing, typeof SubscriptUI];
  static get pluginName(): "Subscript";
  static get isOfficialPlugin(): true;
}

/**
 * Complete superscript formatting feature combining editing and UI
 */
class Superscript extends Plugin {
  static get requires(): readonly [typeof SuperscriptEditing, typeof SuperscriptUI];
  static get pluginName(): "Superscript"; 
  static get isOfficialPlugin(): true;
}

/**
 * Complete underline formatting feature combining editing and UI
 */
class Underline extends Plugin {
  static get requires(): readonly [typeof UnderlineEditing, typeof UnderlineUI];
  static get pluginName(): "Underline";
  static get isOfficialPlugin(): true;
}

Editing Plugins

Handle model attributes, schema configuration, view conversion, and command registration.

/**
 * Bold editing functionality - registers 'bold' command and handles model/view conversion
 */
class BoldEditing extends Plugin {
  static get pluginName(): "BoldEditing";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Italic editing functionality - registers 'italic' command and handles model/view conversion  
 */
class ItalicEditing extends Plugin {
  static get pluginName(): "ItalicEditing";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Code editing functionality - registers 'code' command with special caret movement
 */
class CodeEditing extends Plugin {
  static get pluginName(): "CodeEditing";
  static get isOfficialPlugin(): true;
  static get requires(): readonly [typeof TwoStepCaretMovement];
  init(): void;
}

/**
 * Strikethrough editing functionality - registers 'strikethrough' command
 */
class StrikethroughEditing extends Plugin {
  static get pluginName(): "StrikethroughEditing";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Subscript editing functionality - registers 'subscript' command
 */
class SubscriptEditing extends Plugin {
  static get pluginName(): "SubscriptEditing";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Superscript editing functionality - registers 'superscript' command
 */
class SuperscriptEditing extends Plugin {
  static get pluginName(): "SuperscriptEditing";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Underline editing functionality - registers 'underline' command
 */
class UnderlineEditing extends Plugin {
  static get pluginName(): "UnderlineEditing";
  static get isOfficialPlugin(): true;
  init(): void;
}

UI Plugins

Provide toolbar buttons and menu bar items for text formatting features.

/**
 * Bold UI functionality - provides bold button for toolbar and menu
 */
class BoldUI extends Plugin {
  static get pluginName(): "BoldUI";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Italic UI functionality - provides italic button for toolbar and menu
 */
class ItalicUI extends Plugin {
  static get pluginName(): "ItalicUI";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Code UI functionality - provides code button for toolbar and menu
 */
class CodeUI extends Plugin {
  static get pluginName(): "CodeUI";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Strikethrough UI functionality - provides strikethrough button for toolbar and menu
 */
class StrikethroughUI extends Plugin {
  static get pluginName(): "StrikethroughUI";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Subscript UI functionality - provides subscript button for toolbar and menu
 */
class SubscriptUI extends Plugin {
  static get pluginName(): "SubscriptUI";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Superscript UI functionality - provides superscript button for toolbar and menu
 */
class SuperscriptUI extends Plugin {
  static get pluginName(): "SuperscriptUI";
  static get isOfficialPlugin(): true;
  init(): void;
}

/**
 * Underline UI functionality - provides underline button for toolbar and menu
 */
class UnderlineUI extends Plugin {
  static get pluginName(): "UnderlineUI";
  static get isOfficialPlugin(): true;
  init(): void;
}

Command System

Base command class for text attribute toggling functionality.

/**
 * Base command class for toggling text attributes on/off
 */
class AttributeCommand extends Command {
  /** Whether the command is currently active (attribute is applied) */
  readonly value: boolean;
  
  /** The attribute key this command manages */
  readonly attributeKey: string;
  
  /**
   * Creates a new attribute command
   * @param editor - Editor instance
   * @param attributeKey - Model attribute key to manage
   */
  constructor(editor: Editor, attributeKey: string);
  
  /**
   * Updates command state based on current selection
   */
  refresh(): void;
  
  /**
   * Executes the command - toggles attribute on/off
   * @param options - Execution options
   * @param options.forceValue - Force specific value instead of toggling
   */
  execute(options?: { forceValue?: boolean }): void;
}

Utility Functions

Internal utility function for creating UI buttons (exported with underscore prefix).

/**
 * Creates button factory function for basic style features (internal utility)
 * @param config - Button configuration
 * @param config.editor - Editor instance
 * @param config.commandName - Name of the command to execute
 * @param config.plugin - Plugin instance for event listening
 * @param config.icon - Icon for the button
 * @param config.label - Accessible label for the button
 * @param config.keystroke - Optional keyboard shortcut
 * @returns Function that creates ButtonView or MenuBarMenuListItemButtonView
 */
function _getBasicStylesButtonCreator(config: {
  editor: Editor;
  commandName: string;
  plugin: Plugin;
  icon: string;
  label: string;
  keystroke?: string;
}): <T extends typeof ButtonView | typeof MenuBarMenuListItemButtonView>(
  ButtonClass: T
) => InstanceType<T>;

Programmatic Usage Examples

Executing Commands

// Apply formatting
editor.execute('bold');
editor.execute('italic');
editor.execute('code');

// Remove formatting (if already applied)
editor.execute('bold'); // toggles off if currently bold

// Force specific state
editor.execute('bold', { forceValue: true });  // force bold on
editor.execute('bold', { forceValue: false }); // force bold off

Checking Command State

const boldCommand = editor.commands.get('bold') as AttributeCommand;
const italicCommand = editor.commands.get('italic') as AttributeCommand;

// Check if formatting is active
console.log('Text is bold:', boldCommand.value);
console.log('Text is italic:', italicCommand.value);

// Check if command is enabled (can be executed)
console.log('Bold can be applied:', boldCommand.isEnabled);
console.log('Italic can be applied:', italicCommand.isEnabled);

Listening to Command Changes

const boldCommand = editor.commands.get('bold') as AttributeCommand;

// Listen for state changes
boldCommand.on('change:value', (evt, propertyName, newValue, oldValue) => {
  console.log('Bold state changed:', newValue);
});

boldCommand.on('change:isEnabled', (evt, propertyName, newValue, oldValue) => {
  console.log('Bold availability changed:', newValue);
});

HTML Output Mapping

The package converts model attributes to the following HTML elements:

  • bold → <strong> (accepts <b>, CSS font-weight: bold/600+)
  • italic → <i> (accepts <em>, CSS font-style: italic)
  • code → <code>
  • strikethrough → <s> (accepts <del>, CSS text-decoration: line-through)
  • subscript → <sub>
  • superscript → <sup>
  • underline → <u> (accepts CSS text-decoration: underline)

Keyboard Shortcuts

Built-in keyboard shortcuts:

  • Ctrl+B - Toggle bold formatting
  • Ctrl+I - Toggle italic formatting
  • Arrow keys - Special navigation behavior when inside inline code (two-step caret movement)

Two-Step Caret Movement for Code

The Code feature includes special navigation behavior:

  • Double Left Arrow - Move caret out of inline code to the left
  • Double Right Arrow - Move caret out of inline code to the right
  • This prevents the caret from getting trapped inside inline code elements
  • Provides visual highlight when code element is selected

CSS Integration

The package includes CSS integration with CKEditor 5's theme system:

  • Inline code elements receive the ck-code_selected class when selected
  • Theme styles are applied automatically when using @ckeditor/ckeditor5-theme-lark
  • Custom styling can be applied through CSS targeting the generated HTML elements

Error Handling

Commands automatically handle validation through CKEditor 5's schema system:

  • Commands are automatically disabled when the attribute cannot be applied to the current selection
  • Invalid operations are prevented at the command level
  • Schema violations are handled gracefully without throwing errors

Types

interface Editor {
  commands: CommandCollection;
  execute(commandName: string, options?: any): any;
  model: Model;
  conversion: Conversion;
  keystrokes: KeystrokeHandler;
  accessibility: Accessibility; 
  plugins: PluginCollection;
  ui: EditorUI;
  locale: Locale;
  editing: EditingController;
}

interface Command {
  value: any;
  isEnabled: boolean;
  refresh(): void;
  execute(options?: any): void;
  on(event: string, callback: Function): void;
  editor: Editor;
}

interface Plugin {
  static pluginName: string;
  static requires?: readonly any[];
  static isOfficialPlugin?: boolean;
  init?(): void;
  editor: Editor;
  listenTo(emitter: any, event: string, callback: Function): void;
}

interface CommandCollection {
  get(name: string): Command | undefined;
  add(name: string, command: Command): void;
}

interface TwoStepCaretMovement extends Plugin {
  registerAttribute(attributeName: string): void;
}

interface ButtonView {
  set(properties: any): void;
  bind(property: string): any;
}

interface MenuBarMenuListItemButtonView {
  set(properties: any): void;
  bind(property: string): any;
}

interface Model {
  schema: ModelSchema;
  document: ModelDocument;
  change(callback: (writer: Writer) => void): void;
}

interface ModelSchema {
  extend(itemName: string, definition: any): void;
  setAttributeProperties(attributeName: string, properties: any): void;
  checkAttributeInSelection(selection: Selection, attributeName: string): boolean;
  checkAttribute(item: any, attributeName: string): boolean;
  getValidRanges(ranges: any[], attributeName: string): any[];
}

interface Conversion {
  attributeToElement(config: any): void;
}

interface KeystrokeHandler {
  set(keystroke: string, command: string): void;
}

interface Accessibility {
  addKeystrokeInfos(config: any): void;
}