or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

CKEditor 5 Block Quote

The CKEditor 5 Block Quote package provides comprehensive block quote functionality for the CKEditor 5 rich text editor. It enables users to format text as quotations with proper semantic HTML <blockquote> elements, complete with editing capabilities, UI integration, and keyboard interaction support.

Package Information

Package Name: @ckeditor/ckeditor5-block-quote
Package Type: npm
Language: TypeScript
Installation: npm install @ckeditor/ckeditor5-block-quote (or included in main ckeditor5 package)
Dependencies: @ckeditor/ckeditor5-core, @ckeditor/ckeditor5-enter, @ckeditor/ckeditor5-icons, @ckeditor/ckeditor5-typing, @ckeditor/ckeditor5-ui, @ckeditor/ckeditor5-utils

Core Imports

import { BlockQuote, BlockQuoteEditing, BlockQuoteUI, BlockQuoteCommand } from '@ckeditor/ckeditor5-block-quote';

From main ckeditor5 package:

import { BlockQuote, BlockQuoteEditing, BlockQuoteUI, BlockQuoteCommand } from 'ckeditor5';

For CommonJS:

const { BlockQuote } = require('@ckeditor/ckeditor5-block-quote');

Types

Core CKEditor 5 types referenced in the API:

Core types from CKEditor 5 framework:

// From '@ckeditor/ckeditor5-core'
interface Editor {
  commands: CommandCollection;
  model: Model;
  editing: EditingController;
  ui: EditorUI;
  execute(commandName: string, ...args: any[]): any;
}

abstract class Plugin {
  readonly editor: Editor;
  constructor(editor: Editor);
  init?(): void;
  destroy?(): void;
  static get requires?(): Array<typeof Plugin>;
  static get pluginName?(): string;
  static get isOfficialPlugin?(): boolean;
}

abstract class Command {
  readonly editor: Editor;
  isEnabled: boolean;
  value: any;
  constructor(editor: Editor);
  refresh(): void;
  execute(...args: any[]): void;
}

// From '@ckeditor/ckeditor5-enter'
class Enter extends Plugin {
  static get pluginName(): 'Enter';
}

// From '@ckeditor/ckeditor5-typing'
class Delete extends Plugin {
  static get pluginName(): 'Delete';
}

Basic Usage

import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';
import { BlockQuote } from '@ckeditor/ckeditor5-block-quote';
import { Essentials } from '@ckeditor/ckeditor5-essentials';
import { Paragraph } from '@ckeditor/ckeditor5-paragraph';

ClassicEditor
  .create(document.querySelector('#editor')!, {
    plugins: [Essentials, Paragraph, BlockQuote],
    toolbar: ['blockQuote']
  })
  .then(editor => {
    // Execute block quote command programmatically
    editor.execute('blockQuote');
    
    // Check if selection is in a block quote
    const command = editor.commands.get('blockQuote')!;
    console.log('Is in block quote:', command.value);
  })
  .catch(error => {
    console.error(error);
  });

Architecture

The CKEditor 5 Block Quote package follows the standard CKEditor 5 plugin architecture:

BlockQuote: Main plugin that orchestrates editing and UI functionality
BlockQuoteEditing: Handles model schema, view conversion, and keyboard behaviors
BlockQuoteUI: Provides toolbar buttons and menu items for user interaction
BlockQuoteCommand: Implements the core logic for applying and removing block quotes
Type Augmentation: Extends CKEditor 5 core types for plugin and command registration

Capabilities

Main Block Quote Plugin

The primary entry point that combines all block quote functionality into a single, easy-to-use plugin.

/**
 * The main block quote plugin that loads editing and UI features
 */
export class BlockQuote extends Plugin {
  /** Required plugins: BlockQuoteEditing and BlockQuoteUI */
  static get requires(): readonly [typeof BlockQuoteEditing, typeof BlockQuoteUI];
  /** Plugin name identifier */
  static get pluginName(): 'BlockQuote';
  /** Official CKEditor 5 plugin flag */
  static override get isOfficialPlugin(): true;
}

Block Quote Editing

Handles the core editing functionality including model schema, view conversions, and keyboard interactions.

/**
 * Block quote editing plugin that handles model/view logic and keyboard behaviors
 */  
export class BlockQuoteEditing extends Plugin {
  /** Plugin name identifier */
  static get pluginName(): 'BlockQuoteEditing';
  /** Official CKEditor 5 plugin flag */
  static override get isOfficialPlugin(): true;
  /** Required plugins for keyboard handling */
  static get requires(): readonly [typeof Enter, typeof Delete];
  /** Initialize the editing features */
  init(): void;
}

The init() method sets up:

Model schema registration for 'blockQuote' element
Bidirectional conversion between model 'blockQuote' and view 'blockquote' elements
Command registration for 'blockQuote' command
Post-fixer for cleaning invalid block quote states
Enter key behavior: breaks out of empty block quotes
Backspace key behavior: breaks out of block quotes at beginning

Block Quote UI

Provides user interface components including toolbar buttons and menu items.

/**
 * Block quote UI plugin that provides toolbar and menu components
 */
export class BlockQuoteUI extends Plugin {
  /** Plugin name identifier */
  static get pluginName(): 'BlockQuoteUI';
  /** Official CKEditor 5 plugin flag */  
  static override get isOfficialPlugin(): true;
  /** Initialize UI components */
  init(): void;
}

The init() method creates:

'blockQuote' toolbar button with quote icon and tooltip
'menuBar:blockQuote' menu item with checkbox role
Both components are bound to the block quote command state

Block Quote Command

Implements the command logic for applying and removing block quotes from selected content.

/**
 * Block quote command that handles applying and removing block quotes
 */
export class BlockQuoteCommand extends Command {
  /** Whether the selection starts in a block quote (observable, readonly) */
  declare public value: boolean;
  /** Updates command state based on current selection */
  override refresh(): void;
  /** Executes the command to apply or remove block quotes */
  override execute(options?: BlockQuoteCommandExecuteOptions): void;
}

interface BlockQuoteCommandExecuteOptions {
  /** If set, forces command behavior: true=apply, false=remove, undefined=toggle */
  forceValue?: boolean;
}

Command Behavior:

When value is false: Wraps selected blocks in block quotes
When value is true: Removes block quote formatting from selected blocks
Supports partial block quote removal with automatic splitting
Merges adjacent block quotes when applying to consecutive blocks

Usage Examples:

// Toggle block quote (default behavior)
editor.execute('blockQuote');

// Force apply block quote
editor.execute('blockQuote', { forceValue: true });

// Force remove block quote
editor.execute('blockQuote', { forceValue: false });

// Check current state
const command = editor.commands.get('blockQuote');
console.log('Selection in block quote:', command.value);
console.log('Command enabled:', command.isEnabled);

Type Augmentation

Extends CKEditor 5 core type definitions to include block quote plugin and command types.

declare module '@ckeditor/ckeditor5-core' {
  interface PluginsMap {
    [BlockQuote.pluginName]: BlockQuote;
    [BlockQuoteEditing.pluginName]: BlockQuoteEditing;
    [BlockQuoteUI.pluginName]: BlockQuoteUI;
  }

  interface CommandsMap {
    blockQuote: BlockQuoteCommand;
  }
}

Model Schema

The block quote feature registers a 'blockQuote' element in the model schema with the following properties:

Inherits from: $container - can contain other block elements
Allowed children: Any block-level content (paragraphs, headings, lists, etc.)
HTML output: <blockquote> element
Nesting: Supports nested block quotes

Keyboard Integration

The plugin provides enhanced keyboard behavior within block quotes:

Enter Key: When pressed in an empty block within a quote, breaks out of the quote
Backspace Key: When pressed at the beginning of a quote, breaks out of the quote
Both behaviors are contextual and only activate when the selection is within a block quote

Styling

The package includes default CSS styling for block quotes:

.ck-content blockquote {
  overflow: hidden;
  padding-right: 1.5em;
  padding-left: 1.5em;
  margin-left: 0;
  margin-right: 0;
  font-style: italic;
  border-left: solid 5px hsl(0, 0%, 80%);
}

.ck-content[dir="rtl"] blockquote {
  border-left: 0;
  border-right: solid 5px hsl(0, 0%, 80%);
}

Error Handling

The editing plugin includes automatic post-fixing for invalid block quote states:

Empty block quotes: Automatically removed when they become empty
Invalid positioning: Block quotes placed in invalid locations are unwrapped
Schema validation: Ensures all content within block quotes meets schema requirements

Integration Examples

With Custom Editor Build

import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';
import { BlockQuote } from '@ckeditor/ckeditor5-block-quote';
import { Essentials } from '@ckeditor/ckeditor5-essentials';
import { Paragraph } from '@ckeditor/ckeditor5-paragraph';

ClassicEditor
  .create(document.querySelector('#editor')!, {
    plugins: [Essentials, Paragraph, BlockQuote],
    toolbar: ['blockQuote']
  })
  .catch(error => {
    console.error(error);
  });

Programmatic Usage

// Apply block quote to current selection
editor.execute('blockQuote');

// Listen for command state changes
const command = editor.commands.get('blockQuote');
command.on('change:value', () => {
  console.log('Block quote state changed:', command.value);
});

// Check if command is available
if (command.isEnabled) {
  editor.execute('blockQuote');
}