CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ckeditor--ckeditor5-block-quote

Block quote feature for CKEditor 5 rich text editor that enables formatting text as quotations.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

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');
}

docs

index.md

tile.json