---
title: "Ruby Text extension"
description: "Add HTML ruby text annotations and furigana to your Tiptap Editor."
canonical_url: "https://tiptap.dev/docs/editor/extensions/marks/ruby-text"
---

# Ruby Text extension

Add HTML ruby text annotations and furigana to your Tiptap Editor.

The Ruby Text extension adds support for [HTML ruby annotations](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ruby). Ruby annotations provide reading guides for CJK text, such as furigana for Japanese. It is not related to the Ruby programming language.

> **Interactive demo:** [RubyText](https://embed.tiptap.dev/preview/Marks/RubyText)

## Install

```bash
npm install @tiptap/extension-ruby-text
```

## Usage

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

```js
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.

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

> **HTML parsing:**
>
> The extension accepts ruby elements with an `rb` child or direct base text. It ignores `rp`
> fallback elements. Ruby elements without an `rt` annotation are not parsed as Ruby Text marks.

## Settings

### HTMLAttributes

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

Default: `{}`

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

### allowClickToEdit

Controls whether clicking an annotation opens the inline editor.

Default: `true`

```js
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.

```js
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.

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

### toggleRubyText()

Adds or removes a ruby annotation on the selected text.

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

### unsetRubyText()

Removes the ruby annotation from the selected text.

```js
editor.commands.unsetRubyText()
```

## Source code

[packages/extension-ruby-text/](https://github.com/ueberdosis/tiptap/tree/main/packages/extension-ruby-text/)