Quillのツールバーにカスタムボタンを追加する【Laravel】

リッチテキストエディタ『Quill』のツールバーに、独自のボタンを追加する方法を解説します。

結論から書くと、ツールバーのHTMLに ql- で始まるクラスのボタンを置き、handlers でそのクラス名に対応する処理を書きます。ボタンの見た目はHTML側、動作はJavaScript側で分担する形です。

この記事は2022年の公開時に誤った実装例を掲載していました。2026年9月に、Quill 2.0.3 で動く正しいコードへ全面的に差し替えています。

Quillにカスタムボタンを追加する

結論：ツールバーを自分でHTMLとして書き、そのコンテナをQuillに渡します。ボタンのクラス名を ql-任意の名前 にしておくと、その名前でハンドラを登録できます。

まずツールバーのHTMLを用意します。

<div id="toolbar">
  <button class="ql-bold"></button>
  <button class="ql-italic"></button>
  <!-- ここが独自のボタン -->
  <button class="ql-insertStar">★</button>
</div>

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

ql-bold や ql-italic のようにQuillが最初から知っている名前は、中身を空にしておけばアイコンが自動で入ります。独自のボタンはQuillが知らないので、中身に文字やアイコンを自分で書きます。

次に、そのコンテナをQuillに渡し、ハンドラを登録します。

const quill = new Quill('#editor', {
  theme: 'snow',
  modules: {
    toolbar: {
      container: '#toolbar',
      handlers: {
        // クラス名の ql- を除いた部分がキーになる
        insertStar: function () {
          const range = this.quill.getSelection(true);
          this.quill.insertText(range.index, '★');
          this.quill.setSelection(range.index + 1);
        }
      }
    }
  }
});

handlers のキーは、クラス名から ql- を取り除いた文字列です。ql-insertStar なら insertStar になります。ここが一致していないと、ボタンを押しても何も起きません。

ハンドラの中の this はツールバーのモジュールを指すので、エディタ本体には this.quill でアクセスします。

初期化のあとから追加する

すでに動いているエディタにハンドラを足す場合は、addHandler() を使います。

const toolbar = quill.getModule('toolbar');

toolbar.addHandler('insertStar', function () {
  const range = this.quill.getSelection(true);
  this.quill.insertText(range.index, '★');
});

既定のボタンの動作を差し替えたいときにも使えます。たとえば画像ボタンを押したときに、自前のアップロード画面を出す、といった用途です。

toolbar.addHandler('image', function () {
  // 独自の画像アップロード処理を呼ぶ
  openImageUploader();
});

ボタンのCSSスタイルを変更する

結論：追加したボタンは .ql-insertStar というクラスで指定できます。

/* 独自ボタンの見た目 */
.ql-toolbar .ql-insertStar {
  font-size: 18px;
  color: #444;
}

/* ホバー時とアクティブ時 */
.ql-toolbar .ql-insertStar:hover {
  color: #06c;
}

Quillの既定のボタンは中身がSVGです。アイコンの色を変えたい場合は、SVGの stroke と fill を指定します。

.ql-toolbar button:hover .ql-stroke {
  stroke: #06c;
}

.ql-toolbar button:hover .ql-fill {
  fill: #06c;
}

.ql-stroke は線、.ql-fill は塗りです。ボタンによってどちらが使われているかが違うので、色が変わらないときはもう一方も指定してみてください。

アイコンを画像やアイコンフォントにする

結論：ボタンの中身はただのHTMLなので、<svg> でもアイコンフォントでも入れられます。

<button class="ql-insertStar">
  <i class="fa-solid fa-star"></i>
</button>

Font Awesome を使う場合は、7系のクラス名で書いてください。4系の fa fa-star という書き方は、現在のバージョンでは表示されません。

つまずきやすい点

結論：ボタンが反応しないときは、クラス名とハンドラのキーが一致しているかを最初に確認してください。

▼よくある原因

症状	原因
押しても何も起きない	クラス名とハンドラのキーが不一致
ツールバーが二重に出る	`container` を指定せず配列も渡している
ボタンが空欄になる	Quillが知らない名前なのに中身を書いていない
選択位置がずれる	`getSelection(true)` の `true` を省いている