<ruby>

Definition and Usage

The <ruby> element specifies a ruby annotation, which is a small text displayed above or beside the base text, typically used in East Asian typography for pronunciation or translation guides.

The <ruby> element is used with the <rt> tag (ruby text) and optionally with the <rp> tag (ruby parentheses) for fallback support.

Ruby annotations are commonly used in:

• Japanese: Furigana (hiragana or katakana reading guides above kanji)
• Chinese: Pinyin (romanized pronunciation above characters)
• Korean: Hanja pronunciation guides
• Educational materials: Teaching pronunciation to language learners
• Dictionaries: Showing pronunciation or definitions

Attributes

The <ruby> tag supports the Global Attributes in HTML.

The <ruby> tag also supports the Event Attributes in HTML.

Examples

Basic Japanese Furigana

Add furigana reading guide for Japanese kanji:

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

Chinese Pinyin

Add pinyin pronunciation for Chinese characters:

<ruby>
  中国
  <rt>Zhōngguó</rt>
</ruby>

With Fallback Parentheses

Include <rp> tags for browsers without ruby support:

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

Multiple Ruby Annotations

Add annotations to multiple words in a sentence:

<p
  >
  私は
  <ruby>日本語<rt>にほんご</rt></ruby
  >を
  <ruby>勉強<rt>べんきょう</rt></ruby
  >しています。
</p
>

Complex Ruby Structure

Multiple characters with individual annotations:

<ruby>
  明日
  <rt>あした</rt>
</ruby
>は
<ruby>
  天気
  <rt>てんき</rt>
</ruby>が
<ruby>
  良い
  <rt>よい</rt>
</ruby>です。

Styled Ruby Annotations

Customize ruby annotation appearance with CSS:

<style>
  ruby {
    font-size: 28px;
    font-weight: 500;
  }

  rt {
    font-size: 14px;
    color: #745af2;
    font-weight: 600;
  }

  .highlight rt {
    background-color: #fff3cd;
    padding: 2px 4px;
    border-radius: 3px;
  }
</style>

<ruby class="highlight">
  北京
  <rt>Běijīng</rt>
</ruby>

Ruby Structure Explained

A complete ruby annotation consists of the following components:

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

• <ruby>: Container element for the entire annotation
• Base text: The main text to be annotated (e.g., kanji characters)
• <rt>: The annotation text displayed above/beside the base text
• <rp>: Optional fallback parentheses for browsers without ruby support

East Asian Typography

Ruby annotations are an essential part of East Asian typography, serving several important purposes:

• Pronunciation Guides: Help readers pronounce unfamiliar or complex characters
• Language Learning: Essential tool for students learning Japanese, Chinese, or Korean
• Children's Literature: Make books accessible to young readers who haven't learned all characters yet
• Technical Terms: Provide pronunciation for specialized vocabulary or jargon
• Proper Names: Clarify pronunciation of names, especially foreign names written in local script
• Accessibility: Help readers with reading difficulties or visual impairments

Use Cases

• Japanese Furigana: Hiragana or katakana pronunciation above kanji characters
• Chinese Pinyin: Romanized pronunciation system to help with character reading
• Korean Hanja: Hangul pronunciation guides for Chinese characters used in Korean
• Educational Materials: Textbooks, learning apps, and language courses
• Manga and Comics: Adding reading guides for younger audiences
• News Articles: Helping readers with difficult or uncommon characters
• Dictionaries: Showing pronunciation alongside word definitions

Try it Yourself

Best Practices

• Always include <rp> tags for fallback support in older browsers
• Use appropriate font sizes - ruby text should be smaller but still readable
• Structure ruby properly: place <rt> immediately after the base text it annotates
• Keep annotations concise and relevant to the base text
• Consider your audience - not all readers need ruby annotations
• Test in multiple browsers to ensure consistent rendering
• Use CSS to style ruby text for better visual hierarchy
• Ensure proper character encoding (UTF-8) for East Asian characters
• Don't overuse ruby - annotate only where necessary

Default CSS Settings

Most browsers will display the <ruby> element with the following default values:

ruby {
  display: ruby;
}

rt {
  display: ruby-text;
  font-size: 50%;
  line-height: 1;
}

Related Tags

• <rt>

  Defines ruby text annotation

• <rp>

  Defines fallback parentheses

• <rb>

  Defines ruby base text

• <rtc>

  Defines ruby text container

• <rbc>

  Defines ruby base container