HTML Ruby Annotations: The `<ruby>` Tag Explained

HTML <ruby> Tag

The <ruby> tag in HTML is used to define a ruby annotation, which is a small text positioned above or to the right of the base text. This is commonly used in East Asian typography, particularly with languages like Japanese, Chinese, and Korean, to provide phonetic guides or clarification for characters. Ruby annotations enhance readability by giving pronunciations (furigana) for complex characters or providing alternative meanings.

Syntax

<ruby>
  <rb>base text</rb>
  <rp>(</rp><rt>ruby text</rt><rp>)</rp>
</ruby>

<ruby>
  <rb>base text</rb>
  <rtc>
    <rt>ruby text 1</rt>
    <rt>ruby text 2</rt>
  </rtc>
</ruby>

Attributes

Example

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

This basic example shows the kanji for "Tokyo" with its phonetic pronunciation (furigana) "toukyou" in parentheses.

More Examples

Example 1: Simple Ruby Annotation

This example shows a common use case for providing pronunciation hints.

<p>
  The <ruby><rb>漢字</rb><rp>(</rp><rt>かんじ</rt><rp>)</rp></ruby> is the word for kanji.
</p>

Example 2: Multiple Ruby Texts Using <rtc>

The <rtc> tag allows multiple <rt> elements, which is useful when multiple layers of annotations are needed, or different types of annotations are required.

<ruby>
    <rb>昨日</rb>
    <rtc>
        <rt>さくじつ</rt>
        <rt>きのう</rt>
    </rtc>
</ruby>

In this case we show two ways to read 昨日, "sakujitsu" and "kinou".

Example 3: Using <rp> for Fallback

The <rp> tags ensure that the parentheses around ruby text are displayed only by browsers that do not support ruby.

<p>
  <ruby><rb>大人</rb><rp>(</rp><rt>おとな</rt><rp>)</rp></ruby> is the word for adult.
</p>

<p>
<ruby><rb>難しい</rb><rp>(</rp><rt>むずかしい</rt><rp>)</rp></ruby> means difficult.
</p>

Example 4: Styling Ruby Annotations

You can use CSS to style the ruby text to look different than the base text:

<style>
    ruby rt {
        font-size: 0.8em;
        color: blue;
    }
</style>

<p>
   <ruby><rb>今日</rb><rp>(</rp><rt>きょう</rt><rp>)</rp></ruby> is the word for today.
</p>

Example 5: Complex Example with Different Characters

<p>
  <ruby><rb>日本語</rb><rp>(</rp><rt>にほんご</rt><rp>)</rp></ruby> can be hard to learn, but <ruby><rb>面白い</rb><rp>(</rp><rt>おもしろい</rt><rp>)</rp></ruby>!
</p>

Browser Support

The <ruby> tag and its associated tags are well-supported across modern browsers.

Notes and Tips

• Ruby annotations are extremely useful for languages with complex character systems where pronunciation guidance is needed, or to give hints at the meanings of characters.
• Use the <rp> tags to provide fallback for browsers that do not support ruby annotations.
• When using multiple <rt> elements inside an <rtc>, make sure each of them is providing a relevant and clear annotation.
• Consider using CSS for enhanced styling of your ruby annotations for a better and more integrated experience with the rest of your site's style.
• Always check how ruby text is rendering on different browsers and devices to ensure correct presentation.
• While primarily used for East Asian languages, you can use ruby annotations creatively in other contexts as well, so long as you ensure the context makes sense for users.
• Keep the base text and ruby text clear and concise for better user experience.