Editor.js

A Tool is a class that provides a custom Block type (e.g., Text, Image, Header). To create a tool, you must implement a class structure that includes a constructor and a render method.

Required Methods

• constructor({data, config, api, block}): Initializes the tool instance.
  • data: Data to be rendered.
  • config: Special configuration parameters.
  • api: Editor.js API methods.
  • block: Block's API methods.
• render(): Returns an HTMLElement that will be placed into the Editor.
• save(): Processes the tool's element in the DOM and returns the block's data.

Optional Methods

• validate(data: BlockToolData): boolean | Promise<boolean>: Validates the tool's data before saving. If it returns false, the data won't be saved.
• merge(data): Specifies how to merge two blocks of the same type (e.g., on Backspace).

class MyCustomTool {
  constructor({data, config, api}) {
    this.data = data;
    this.api = api;
    this.config = config;
  }

  render() {
    const div = document.createElement('DIV');
    div.innerHTML = 'Hello World';
    return div;
  }

  save() {
    return { text: 'Hello World' };
  }
}

Inline Tools are used to manipulate selected fragments of text (e.g., bold, italic, or links). To create one, your class must implement a static getter isInline set to true and provide specific methods to handle rendering and text manipulation.

Required Methods

• render(): Returns an HTMLElement representing the button to be added to the Inline Toolbar.
• surround(range: Range): Receives the selected Range and performs the text wrapping/transformation.
• checkState(selection: Selection): Returns a Boolean indicating if the tool is currently active for the given selection (used to highlight the button).

Optional Methods

• renderActions(): Returns an HTMLElement (like an input or textarea) to be displayed below the main buttons (e.g., for entering a URL in a link tool).
• clear(): Logic to reset the tool's state (like clearing inputs) when the toolbar opens or closes.
• static get sanitize(): Provides a configuration object to ensure the HTML tags generated by your tool are not stripped by the editor's sanitizer.

export default class BoldInlineTool implements InlineTool {
  public static isInline = true;
  public static title = 'Bold';

  render() {
    const button = document.createElement('button');
    button.innerHTML = '<b>B</b>';
    return button;
  }

  surround(range: Range) {
    // logic to wrap text in <b> tags
  }

  checkState(selection: Selection): boolean {
    // logic to check if selection is already bold
    return false;
  }
}

Editor.js allows tools to intercept and process pasted content (HTML, text patterns, or files). To implement this, you must define a static pasteConfig getter and a public onPaste method.

1. Define pasteConfig patterns

Your pasteConfig can handle three scenarios:

• HTML Tags: Provide a tags array. You can also specify which attributes to keep (e.g., { img: { src: true } }).
• RegExp: Provide a patterns object where keys are names and values are RegExp objects. (Note: Only works if pasted on defaultBlock and string length < 450).
• Files: Provide a files object with extensions or mimeTypes arrays.

2. Implement onPaste(event)

The onPaste method receives a PasteEvent object. You should switch on event.type ('tag', 'pattern', or 'file') to access the event.detail.

class MyTool {
  static get pasteConfig() {
    return {
      tags: ['H1', 'H2'],
      patterns: {
        youtube: /http(?:s?):\/\/(?:www\.)?youtu(?:be\.com\/watch\?v=|[\w\-\_]*)/
      },
      files: {
        mimeTypes: ['image/png']
      }
    };
  }

  onPaste(event) {
    switch (event.type) {
      case 'tag':
        const element = event.detail.data;
        this.handleHTMLPaste(element);
        break;
      case 'pattern':
        const text = event.detail.data;
        const key = event.detail.key;
        this.handlePatternPaste(key, text);
        break;
      case 'file':
        const file = event.detail.file;
        this.handleFilePaste(file);
        break;
    }
  }
}

To add a feature to the Toolbar's default settings zone (available for all blocks), you must implement a "Tune". A Tune must provide two core methods:

• render(): Returns the HTML string that will be appended to the default settings zone in the toolbar.
• save(): Extracts and returns the data that needs to be persisted in the block's output.

The Tune's constructor receives an object containing:

• api: An object containing public methods from the Editor.js modules (e.g., this.api.blocks.moveDown()).
• settings: An object containing the block's default state (e.g., cover images, anchors, etc.).

import IBlockTune from './block-tune';

export default class YourCustomTune implements IBlockTune {
  public constructor({api, settings}) {
    this.api = api;
    this.settings = settings;
  }

  render() {
    // Return HTML for the toolbar
    return '<div>...</div>';
  }

  save() {
    // Return the data to be saved in the block
    return { customData: 'value' };
  }

  someMethod() {
    // Use the API to manipulate blocks
    this.api.blocks.moveDown();
  }
}