Ruby Text extension

The Ruby Text extension adds support for HTML ruby annotations. Ruby annotations provide reading guides for CJK text, such as furigana for Japanese. It is not related to the Ruby programming language.

Install

npm install @tiptap/extension-ruby-text

Usage

Add the extension to your editor, then apply an annotation to the selected text.

import { Editor } from '@tiptap/core'
import RubyText from '@tiptap/extension-ruby-text'

const editor = new Editor({
  extensions: [
    // Other extensions ...
    RubyText,
  ],
})

editor.commands.setRubyText({ rt: 'とうきょう' })

The extension renders the annotation as HTML ruby text.

<ruby><rb>東京</rb><rt>とうきょう</rt></ruby>

Settings

HTMLAttributes

Custom HTML attributes to add to the rendered <ruby> element.

Default: {}

RubyText.configure({
  HTMLAttributes: {
    class: 'ruby-text',
  },
})

allowClickToEdit

Controls whether clicking an annotation opens the inline editor.

Default: true

RubyText.configure({
  allowClickToEdit: false,
})

The inline editor is only available when the Tiptap editor is editable. When disabled, annotations are displayed without interactive editing.

renderAnnotationEditor

Renders a custom element for editing an annotation. The returned element replaces the default input inside the <rt> element.

The callback receives the current annotation, the Tiptap editor, and submit and dismiss functions. Call submit(value) to save an annotation or dismiss() to close the editor without changing it. Add autofocus to the returned element, or one of its descendants, to receive focus when editing opens.

RubyText.configure({
  renderAnnotationEditor: ({ annotation, submit, dismiss }) => {
    const input = document.createElement('input')

    input.value = annotation
    input.setAttribute('autofocus', '')
    input.addEventListener('keydown', (event) => {
      if (event.key === 'Escape') {
        dismiss()
      }

      if (event.key === 'Enter') {
        submit(input.value)
      }
    })

    return input
  },
})

Without this option, the extension renders a text input. Press Enter to save the annotation, or Escape or blur the input to dismiss it. Enter and Escape do not close the input while an IME composition is active.

Commands

setRubyText()

Adds a ruby annotation to the selected text.

editor.commands.setRubyText({ rt: 'かんじ' })

toggleRubyText()

Adds or removes a ruby annotation on the selected text.

editor.commands.toggleRubyText({ rt: 'かんじ' })

unsetRubyText()

Removes the ruby annotation from the selected text.

editor.commands.unsetRubyText()

Source code

packages/extension-ruby-text/