quill-editor-format-painter

Format Painter plugin for Quill 1.3.7.

This plugin is implemented as a Quill module: modules/formatPainter.

Contents

• Features
• Installation
• Quick start (Native Quill)
• Usage with vue-quill-editor (Vue 2)
• Script tag (UMD)
• Options
• API
• Styling
• Compatibility
• Troubleshooting
• Reporting issues

Features

• Paint once
  • Single click the toolbar button: apply once.
• Continuous paint
  • Double click the toolbar button: keep applying until canceled.
• Capture and apply formats
  • Capture formats from the current selection and apply them to later selections.
• Embed-safe by default
  • Ignores non-text selections (embeds like image/video) by default.
• Cancel behavior
  • Click outside editor/toolbar will disable the painter.
• Toolbar button auto-injection
  • If toolbar is enabled and button.ql-format-painter is not present, the module will append one.

Interaction

• Single click toolbar button
  • Capture formats from current selection
  • Apply them to the next selection
  • Then auto-disable
• Double click toolbar button
  • Capture formats from current selection
  • Keep applying on every selection until disabled
• Cancel
  • Click the button again
  • Or click outside the editor/toolbar (when cancelOnOutsideClick is enabled)

Installation

pnpm add quill-editor-format-painter

Peer dependencies

• quill@>=1.3.7 <3

If you use it in a Vue 2 + vue-quill-editor project (like this repo demo), you also need:

• vue@^2.0.0
• vue-quill-editor@^3.0.0

Quick start (Native Quill, build pipeline)

import Quill + theme css, then create the editor.

import Quill from 'quill';
import 'quill/dist/quill.snow.css';
import { registerFormatPainter } from 'quill-editor-format-painter';

registerFormatPainter(Quill);

const quill = new Quill('#editor', {
  theme: 'snow',
  modules: {
    toolbar: true,
    formatPainter: {
      allowFormats: ['bold', 'italic', 'color', 'background']
    }
  }
});

Usage with vue-quill-editor (Vue 2)

Key rule: register the module before mounting any editor component.

import Vue from 'vue';
import VueQuillEditor from 'vue-quill-editor';
import Quill from 'quill';
import 'quill/dist/quill.snow.css';
import { registerFormatPainter } from 'quill-editor-format-painter';

registerFormatPainter(Quill);
Vue.use(VueQuillEditor);

new Vue({
  el: '#app',
  data: () => ({
    content: 'Select some styled text, then click the format painter button.',
    editorOption: {
      theme: 'snow',
      modules: {
        toolbar: [
          ['bold', 'italic', 'underline', 'strike'],
          [{ header: [1, 2, 3, false] }],
          [{ color: [] }, { background: [] }],
          [{ align: [] }],
          [{ list: 'ordered' }, { list: 'bullet' }],
          ['link', 'image']
        ],
        formatPainter: {}
      }
    }
  })
});

Script tag / AMD

For script tag usage, dist/index.global.js exposes window.QuillFormatPainter.

For RequireJS/AMD usage, use the UMD build: dist/index.umd.js.

Note: the CJS build (dist/cjs/index.js) is for Node/bundlers and cannot be loaded directly by RequireJS in browsers.

<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/quill.snow.css" />
<script src="https://unpkg.com/[email protected]/dist/quill.js"></script>
<script src="https://unpkg.com/quill-editor-format-painter/dist/index.global.js"></script>

<div id="editor"></div>

<script>
  QuillFormatPainter.registerFormatPainter(Quill);
  var quill = new Quill('#editor', {
    theme: 'snow',
    modules: { toolbar: true, formatPainter: {} }
  });
</script>

SeaJS (CMD)

CMD is different from AMD. If you are using SeaJS, prefer the global build (dist/index.global.js) and load it as a plain script, or bundle this library into your CMD build pipeline.

RequireJS (AMD)

<script src="https://unpkg.com/[email protected]/dist/quill.js"></script>
<script src="https://unpkg.com/requirejs/require.js"></script>

<script>
  require.config({
    paths: {
      quill: 'https://unpkg.com/[email protected]/dist/quill',
      quillFormatPainter: 'https://unpkg.com/quill-editor-format-painter/dist/index.umd'
    }
  });

  require(['quill', 'quillFormatPainter'], function (Quill, QuillFormatPainter) {
    QuillFormatPainter.registerFormatPainter(Quill);
  });
</script>

Options

Enable it via modules.formatPainter:

modules: {
  toolbar: true,
  formatPainter: {
    // options go here
  }
}

• allowFormats?: string[]
  • If set, only these formats will be captured and applied.
  • Default is a curated list (see source DEFAULT_ALLOW_FORMATS).
• ignoreEmbeds?: boolean (default true)
  • When selection is an embed (image/video/etc.), do nothing.
• cancelOnOutsideClick?: boolean (default true)
  • Click outside editor/toolbar will disable painter.
• toolbarButtonIconSvg?: string
  • Override toolbar icon (svg string).

API

registerFormatPainter(Quill, options?)

Registers the Quill module: modules/formatPainter.

import Quill from 'quill';
import { registerFormatPainter } from 'quill-editor-format-painter';

registerFormatPainter(Quill, {
  iconSvg: '<svg viewBox="0 0 24 24">...</svg>'
});

Module instance

const module = quill.getModule('formatPainter');
module?.disable?.();

Styling

Toolbar button class: ql-format-painter.

.ql-toolbar .ql-format-painter {
  width: 28px;
}

.ql-toolbar.ql-snow .ql-format-painter.ql-active .ql-fill {
  fill: #06c;
}

Compatibility

• Quill: 1.x / 2.x
• Vue integration demo: [email protected] + [email protected]

Development

pnpm i
pnpm dev

Build

pnpm build

Troubleshooting

• Toolbar button does not show up
  • Ensure modules.toolbar is enabled.
  • The module will inject button.ql-format-painter only when a toolbar container exists.
• Nothing happens after clicking
  • The painter captures formats from the current selection. Select some styled text first.
  • If ignoreEmbeds is enabled, selecting a single embed (image/video/iframe) will be ignored.
• Vue 2 integration not working
  • Register the module via registerFormatPainter(Quill) before mounting any editor component.

Reporting issues

Please include:

• Repro steps
  • Minimal code snippet or a repo link
• Expected vs actual behavior
• Versions
  • quill, quill-editor-format-painter
  • Browser + OS
• Any console errors