@paroicms/quill-delta-to-tiptap-json

A lightweight JavaScript/TypeScript library for converting Quill Delta JSON to Tiptap JSON without any dependency. This package provides naive and fast server-side conversion of Quill Delta operations to Tiptap JSON.

Installation

npm install @paroicms/quill-delta-to-tiptap-json

Usage

import { convertQuillDeltaToTiptap } from "@paroicms/quill-delta-to-tiptap-json";

const quillDelta = {
  ops: [
    { insert: "Hello World", attributes: { bold: true } },
    { insert: "\n", attributes: { header: 1 } },
    // ...
  ],
};

const { result, issues } = convertQuillDeltaToTiptap(quillDelta);

console.log(JSON.stringify(result, null, 2));
// {
//   "type": "doc",
//   "content": [
//     {
//       "type": "heading",
//       "attrs": { "level": 1 },
//       "content": [
//         { "type": "text", "text": "Hello World", "marks": [{ "type": "bold" }] }
//       ]
//     },
//     // ...
//   ]
// }

// Check for any issues during conversion
if (issues) {
  console.warn("Conversion issues:", issues);
}

Custom Converters

You can extend the converter with custom handlers for inline formats, block formats, and embeds:

const { result, issues } = convertQuillDeltaToTiptap(quillDelta, {
  customConverters: {
    // Custom inline format (mark)
    inlineFormats: {
      underline: (value, context) => ({
        type: "underline",
      }),
    },
    // Custom block format
    blockFormats: {
      align: (content, value, context) => ({
        type: "paragraph",
        attrs: { textAlign: value },
        content,
      }),
    },
    // Custom embed type
    embeds: {
      image: (value, context) => ({
        type: "image",
        attrs: {
          src: value,
          alt: null,
          title: null,
        },
      }),
      video: (value, context) => ({
        type: "video",
        attrs: { src: value },
      }),
    },
  },
  // Ignore specific attributes (color and background are ignored by default, set to [] to keep them)
  ignoreAttributes: ["color", "background", "font"],
});

Remapping Built-in Formats

You can use custom converters to remap Quill's built-in formats to different Tiptap marks. For example, to convert Quill's underline format to Tiptap's italic mark (mapping <u> to <em>):

const { result } = convertQuillDeltaToTiptap(quillDelta, {
  customConverters: {
    inlineFormats: {
      // Map underline to italic/emphasis
      underline: (value) => (value ? { type: "italic" } : undefined),
    },
  },
});

This pattern is useful when migrating content and you want to change the semantic meaning of certain formats. The value check ensures that falsy values (like { underline: false }) don't add the mark.

API

convertQuillDeltaToTiptap(input: QuillDelta | string, options?: ConverterOptions): ConversionResult

Converts a Quill Delta object or JSON string to Tiptap JSON format.

Parameters:

• input: Quill Delta object
• options (optional): Configuration options
  • customConverters: Custom converter functions for inline formats, block formats, and embeds
  • ignoreAttributes: Array of attribute names to ignore (default: ["color", "background"])

Returns: ConversionResult object containing:

• result: The Tiptap JSON document (type TiptapJsonValue)
• issues (optional): Array of warning messages for skipped or unsupported content

Supported Quill Delta Features

Block-Level Formats

• Headings: { header: 1 } through { header: 6 } → Tiptap headings with bold marks
• Paragraphs: Default block type for regular text
• Blockquotes: { blockquote: true }
• Code blocks: { "code-block": true } or { "code-block": "language" } (with language)
• Lists:
  • Bullet lists: { list: "bullet" }
  • Ordered lists: { list: "ordered" }
  • Nested lists: Supported via { indent: level } attribute

Inline Formats (Marks)

• Bold: { bold: true }
• Italic: { italic: true }
• Strikethrough: { strike: true }
• Inline code: { code: true }
• Superscript: { script: "super" } → Converted to superscript mark
• Subscript: { script: "sub" } → Converted to subscript mark
• Links: { link: "url" } → Converted with target="_blank" and security attributes

Embeds

Embeds are handled through the customConverters.embeds option. Common embed types include:

• Images: { insert: { image: "url" } }
• Videos: { insert: { video: "url" } }
• Custom embeds: Any object-type insert can be handled with a custom converter

Special Handling

• Empty documents: Returns empty doc with no issues
• Unsupported attributes: Logged in issues array (except size which is silently ignored)
• Ignored attributes: Color and background are ignored by default (customizable via options)
• Malformed JSON: Returns empty doc with error in issues
• Mixed embeds and text: Supported on the same line

Differences from Quill

• Color/background: Ignored by default (not standard Tiptap features)

License

MIT

Related Packages

This package can be used as a standalone library. It's also part of the ParoiCMS ecosystem. For more information, visit the ParoiCMS repository.