Quill custom blot: preserve an embedded reference as document data

Suppose a maintenance note needs an equipment reference reading “Pump inspection · EQ-47.” It should behave as one inline item and retain EQ-47 when saved as a Delta. A painted label that loses its equipment ID after reopening is insufficient.

Decide whether you need a format or an embed

Use an inline format when ordinary selected text gains a property, such as a link. Use an inline embed when one position represents a separate object. A block embed belongs on its own line. The equipment reference below is an inline embed; it is an original integration fixture, not a built-in Quill format.

In application code where Quill 2 has already loaded:

const Embed = Quill.import('blots/embed');

class EquipmentRef extends Embed {
  static blotName = 'equipmentRef';
  static tagName = 'span';
  static className = 'equipment-ref';

  static create(value) {
    const node = super.create();
    node.dataset.equipmentId = String(value.id);
    node.dataset.equipmentLabel = String(value.label);
    node.textContent = `${value.label} · ${value.id}`;
    return node;
  }

  static value(node) {
    return {
      id: node.dataset.equipmentId,
      label: node.dataset.equipmentLabel
    };
  }
}

Quill.register(EquipmentRef);

Register this once before constructing or restoring the relevant editors. If your editor restricts formats, include equipmentRef in that configuration. An application with a custom registry must register the blot in the registry that editor actually uses.

The label uses textContent so it becomes text. Validate the object at your application's input boundary as well: this example assumes id and label are supplied by your trusted equipment selection flow. A stored ID does not establish that the current author or reader may access the referenced equipment record.

Insert through Quill and inspect the Delta

With an initialized editor and the blot registered:

const selection = quill.getSelection(true);
const index = selection ? selection.index : quill.getLength() - 1;
quill.insertEmbed(index, 'equipmentRef', {
  id: 'EQ-47',
  label: 'Pump inspection'
}, 'user');
quill.setSelection(index + 1, 0, 'silent');
const savedDocument = quill.getContents();

This example inserts at the selection's start; it does not replace any selected text. Choose replacement behavior explicitly if your product requires it. Quill's content API treats an embed as length one, so the following cursor position is index + 1.

Inspect the relevant Delta operation. Its value should have this shape:

{"insert":{"equipmentRef":{"id":"EQ-47","label":"Pump inspection"}}}

Other text and the document's terminating newline remain separate operations. Do not expect the entire document to equal this one operation. Delta format

Reopen the object, then test its editing behavior

Save the Delta through the real application. In a fresh editor with the same blot registered, restore it through setContents(). Confirm the displayed label and the ID in getContents(). Type before and after the reference, then delete and undo it in your actual integration.

Treat changes to an embed's stored value as a document operation rather than silently changing its inner DOM. Define how a renamed equipment label should behave: preserve the original label, resolve a current label elsewhere, or replace the stored reference deliberately.

The Quill HTML import guide covers migration of supported markup. Importing arbitrary HTML does not guarantee reconstruction of this custom object. For a reader-facing page, define a renderer for equipmentRef and verify that it preserves the intended label and applies the application's access rules before making any reference clickable.