HTML - HTML <ruby>, <rt>, and <rp> Elements for Pronunciation Annotations

HTML provides the <ruby>, <rt>, and <rp> elements for displaying pronunciation, transliteration, or explanatory annotations alongside text. These elements are especially useful for East Asian languages such as Japanese and Chinese, where pronunciation guides may be displayed above or beside characters.

Ruby annotations are not limited to Japanese and Chinese. They can also be useful whenever a webpage needs to associate a short pronunciation or explanatory note with a particular piece of text.

1. What Is Ruby Annotation?

A ruby annotation is a small piece of text displayed alongside or above another piece of text.

For example, in Japanese, the word:

漢字

may be accompanied by its pronunciation:

かんじ

Visually, the browser can present the pronunciation above the original characters.

The important point is that the pronunciation is associated with the original text rather than being treated as ordinary text placed independently on the page.

A simplified representation is:

<ruby>
  漢字
  <rt>かんじ</rt>
</ruby>

The browser understands that かんじ is an annotation for 漢字.

2. The <ruby> Element

The <ruby> element acts as the container for the annotated text and its annotation.

It establishes the relationship between the base text and the associated annotation.

Basic syntax:

<ruby>
  Base Text
  <rt>Annotation</rt>
</ruby>

For example:

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

Here:

  • <ruby> contains the complete ruby annotation.

  • 東京 is the base text.

  • <rt> contains the pronunciation.

  • とうきょう is displayed as the annotation.

The browser determines the appropriate visual placement of the annotation according to the writing system and browser implementation.

3. The <rt> Element

The <rt> element represents the ruby text, meaning the annotation associated with the base characters.

The abbreviation rt comes from "ruby text."

Example:

<ruby>
  日本
  <rt>にほん</rt>
</ruby>

In this example:

日本
にほん

The smaller にほん represents the pronunciation of 日本.

The <rt> element should normally be placed inside a <ruby> element.

4. Why Is <rt> Better Than Ordinary Text?

Suppose you simply write:

<p>漢字 かんじ</p>

The browser sees these as two separate pieces of text. There is no semantic relationship telling the browser that かんじ is the pronunciation of 漢字.

With ruby markup:

<ruby>
  漢字
  <rt>かんじ</rt>
</ruby>

the relationship is explicitly represented in the HTML structure.

This gives browsers and other technologies more meaningful information about the content.

5. The <rp> Element

The <rp> element stands for Ruby Parenthesis.

It provides fallback content for browsers that do not support ruby annotations properly.

For example:

<ruby>
  漢字
  <rp>(</rp>
  <rt>かんじ</rt>
  <rp>)</rp>
</ruby>

A browser that supports ruby annotations can display the annotation in the appropriate ruby position.

A browser without suitable ruby support may instead display something similar to:

漢字(かんじ)

The <rp> content therefore provides a fallback representation.

6. How the Three Elements Work Together

The three elements have different responsibilities:

Element Purpose
<ruby> Container for the base text and its annotation
<rt> Contains the pronunciation or annotation
<rp> Provides fallback characters around the annotation

A typical complete structure is:

<ruby>
  漢字
  <rp>(</rp>
  <rt>かんじ</rt>
  <rp>)</rp>
</ruby>

The relationship can be understood as:

<ruby>
    Base text
        |
        +--- <rt> Annotation
        |
        +--- <rp> Fallback
</ruby>

7. Multiple Ruby Annotations

A page may contain many ruby annotations.

For example:

<p>
  <ruby>日本<rt>にほん</rt></ruby>
  は
  <ruby>美<rt>うつく</rt></ruby>しい
  <ruby>国<rt>くに</rt></ruby>です。
</p>

Each <ruby> element creates an independent relationship between its base text and annotation.

This is useful when only certain words require pronunciation assistance.

8. Ruby Annotations for Language Learning

One of the most useful applications of ruby markup is language education.

For example, a Japanese-learning website could display:

<p>
  <ruby>学校<rt>がっこう</rt></ruby>
</p>

Students can see the original Japanese characters together with their pronunciation.

A more extensive sentence could be written as:

<p>
  <ruby>私<rt>わたし</rt></ruby>は
  <ruby>学校<rt>がっこう</rt></ruby>へ
  <ruby>行<rt>い</rt></ruby>きます。
</p>

This allows learners to associate unfamiliar characters with their pronunciation.

9. Ruby Annotations and Accessibility

Ruby annotations can also contribute to accessible content when used correctly.

They provide structured information about the relationship between the base text and its pronunciation. This is more meaningful than manually positioning small text with CSS.

However, developers should still test ruby content with the browsers and assistive technologies relevant to their audience.

Semantic HTML does not automatically guarantee perfect accessibility in every environment.

10. Ruby Positioning

Ruby text is generally displayed in a smaller size near the base text.

For example, conceptually:

かんじ
漢字

The exact position depends on the writing direction and browser rendering.

For vertical writing, ruby annotations may be positioned differently from horizontal writing.

This is particularly important for Japanese typography because Japanese text can be written horizontally or vertically.

11. Using CSS with Ruby Elements

CSS can be used to control the appearance of ruby annotations.

For example:

<ruby>
  漢字
  <rt>かんじ</rt>
</ruby>

CSS:

ruby {
  font-size: 24px;
}

rt {
  font-size: 12px;
}

The base text and annotation can therefore be given different sizes.

It is generally better to use CSS for presentation rather than attempting to control the visual positioning through unnecessary HTML markup.

12. Ruby and Vertical Writing

Ruby markup becomes particularly valuable when working with languages and layouts that support vertical writing.

CSS can define vertical text direction using properties such as:

.vertical {
  writing-mode: vertical-rl;
}

HTML:

<div class="vertical">
  <ruby>
    漢字
    <rt>かんじ</rt>
  </ruby>
</div>

This allows the ruby annotation to participate naturally in the vertical writing layout.

13. Ruby Is Not the Same as <small>

A common mistake is to think that ruby text is simply smaller text.

For example:

<small>かんじ</small>

only tells the browser that the text has a smaller, less prominent presentation.

It does not establish that かんじ is a pronunciation annotation for another piece of text.

Ruby markup expresses a much more specific relationship:

<ruby>
  漢字
  <rt>かんじ</rt>
</ruby>

Therefore, <ruby> and <rt> should be used when the content is genuinely an annotation associated with the base text.

14. Ruby Is Not the Same as Superscript

Developers may also confuse ruby text with the <sup> element.

For example:

H<sup>2</sup>O

uses <sup> because the 2 has a superscript relationship with H.

Ruby text serves a different purpose:

<ruby>
  漢字
  <rt>かんじ</rt>
</ruby>

Here, the annotation represents pronunciation or related information for the base characters.

Using the correct element gives the HTML document better semantic meaning.

15. Practical Example

Consider a webpage teaching Japanese vocabulary.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Japanese Vocabulary</title>
</head>
<body>

  <h1>Japanese Vocabulary</h1>

  <p>
    <ruby>
      日本
      <rp>(</rp>
      <rt>にほん</rt>
      <rp>)</rp>
    </ruby>
  </p>

  <p>
    <ruby>
      学校
      <rp>(</rp>
      <rt>がっこう</rt>
      <rp>)</rp>
    </ruby>
  </p>

</body>
</html>

This example demonstrates all three elements.

<ruby> establishes the annotation structure.

<rt> provides the Japanese pronunciation.

<rp> supplies parentheses as fallback content when ruby rendering is unavailable.

16. Another Practical Example

A dictionary website could use ruby annotations for difficult characters:

<p>
  <ruby>
    東京
    <rt>とうきょう</rt>
  </ruby>
  is the capital of Japan.
</p>

This makes the pronunciation available without requiring the developer to create a separate pronunciation column or manually position text.

17. Important Advantages

Ruby markup provides several benefits:

Semantic structure:
The HTML explicitly identifies the relationship between the base text and its annotation.

Language learning:
Pronunciation can be displayed directly alongside unfamiliar characters.

Internationalization:
Ruby is designed for writing systems where pronunciation annotations are commonly used.

Fallback support:
<rp> allows developers to provide a useful alternative representation.

Cleaner markup:
Developers do not need to construct complex nested spans solely to position pronunciation text.

CSS compatibility:
Ruby elements can be styled while retaining their semantic meaning.

18. Common Mistakes

A few mistakes should be avoided when using ruby markup.

Mistake 1: Using <rt> outside <ruby>

Incorrect:

<rt>かんじ</rt>

The <rt> element is intended to provide annotation within ruby markup.

Correct:

<ruby>
  漢字
  <rt>かんじ</rt>
</ruby>

Mistake 2: Using ruby only for visual styling

Ruby should not be used merely because the developer wants small text above another piece of text.

If the content is not a genuine annotation, another HTML element may be more appropriate.

Mistake 3: Ignoring fallback content

When broad browser compatibility is important, developers can include <rp>:

<ruby>
  漢字
  <rp>(</rp>
  <rt>かんじ</rt>
  <rp>)</rp>
</ruby>

Mistake 4: Replacing semantic markup with CSS positioning

Developers sometimes create a pronunciation effect with multiple <span> elements and absolute positioning.

For actual ruby annotations, native HTML ruby markup is usually a better foundation because it expresses the intended relationship directly.

19. Ruby Elements in Modern HTML

The <ruby>, <rt>, and <rp> elements are part of HTML's support for more sophisticated text structures and international typography.

Their importance becomes particularly clear when developing:

  • Japanese educational websites

  • Chinese-language resources

  • Digital dictionaries

  • Language-learning applications

  • Children's reading applications

  • Multilingual publishing platforms

  • Digital books

  • International documentation

  • Websites containing pronunciation guides

They allow developers to represent information that would otherwise require complicated visual formatting.

20. Summary

The <ruby>, <rt>, and <rp> elements work together to create pronunciation and explanatory annotations associated with text.

The <ruby> element provides the overall container. The <rt> element contains the actual annotation, such as pronunciation. The <rp> element provides fallback characters for environments where ruby annotations cannot be displayed in their normal form.

A standard pattern is:

<ruby>
  漢字
  <rp>(</rp>
  <rt>かんじ</rt>
  <rp>)</rp>
</ruby>

The most important concept is that ruby markup is semantic HTML for annotations, not simply a technique for making text smaller or positioning text above other text. It is particularly valuable when building multilingual and internationalized websites where pronunciation information needs to be associated directly with written characters.