ruby element

If you don't know what an element is or how you must use it, I recommend you read the "HTML tags and attributes" tutorial that you can find in the HTML tutorials section.

Description

The ruby element provides the means to apply ruby annotations to a run of text. Ruby annotations are short pieces of text that run alongside base text and provide some type of aid to process it. They are mostly used in asian typography, but can be useful for any type of annotations.

Ruby annotated text is marked with the ruby element, while rt provides annotations for all the non-annotated characters found at its left. Additionally, the rp element provides means to hide additional information used to improve the readability in non-supporting browsers. The text inside ruby elements is displayed as a single run of text in browsers that doesn't support it, for which it could be reasonable to provide, for example, parenthesis (hidden inside the rp element) to wrap the annotation.

An rt element provides annotations for all characters at its left that doesn't already have annotations.

Browser support for ruby elements (ruby, rt and rp) isn't complete. Authors may have to rely on styling techniques (CSS) to make ruby annotations work crossbrowser.

Ruby annotations are usually rendered with a smaller font size and on top of the base text. For a better comprehension of how things work, in supporting and non-supporting browsers, we'll take a look at the following code and its approximate rendering in both cases. Parenthesis are provided inside the rp element to aid non-supporting browsers.

This is how the annotation should look in a supporting browser. Note how all the text inside rp elements is completely ignored.

<ruby>Base text<rp> (</rp><rt>Annotation</rt><rp>)</rp></ruby>

Annotation

Base text

Now, this is how non-supporting browsers display the text, ignoring all elements and just showing the information in a simple run of text.

<ruby>Base text<rp> (</rp><rt>Annotation</rt><rp>)</rp></ruby>

Base text (Annotation)

Note: remember that these are only emulations achieved with other supported elements and basic CSS styling.

Examples

The first example contains the word "Tokio" written in japanese. Annotations are provided in hiragana for each character (kanji), serving as a phonetic aid for the reader. This kind of annotation is one of the most common uses for these elements.

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

(とう)(きょう)

Our second example, shows another type of annotations. In this case, the symbols in a poker deck are annotated in order to provide their names and enhance comprehension.

<p>The four symbols in the poker deck are <ruby><rp> (</rp><rt>heart</rt><rp>)</rp></ruby>, <ruby><rp> (</rp><rt>spade</rt><rp>)</rp></ruby>, <ruby><rp> (</rp><rt>club</rt><rp>)</rp></ruby> and <ruby><rp> (</rp><rt>diamond</rt><rp>)</rp></ruby>.</p>

The four symbols in the poker deck are (heart), (spade), (club) and (diamond).

The third example shows a classical text, where some uncommon or ancient english words are annotated with synonyms to help readers comprehend their meaning easily.

<p>Against the which a <ruby>moiety<rp> (</rp><rt>faction, side</rt><rp>)</rp></ruby> competent<br>Was <ruby>gagèd<rp> (</rp><rt>obliged</rt><rp>)</rp></ruby> by our king, which had returned<br>To the inheritance of Fortinbras</p>

Against the which a moiety (faction, side) competent
Was gagèd (obliged) by our king, which had returned
To the inheritance of Fortinbras

The fourth example shows an annotation in which the languages are also specified, for the annotated text as well as for the annotation itself.

<p>Hi everybody! I'm finally in <ruby lang="jp">東京<rt lang="en">Tokyo</rt></ruby>!</p>

Hi everybody! I'm finally in 東京Tokyo!

Attributes

Global attributes

For information about global attributes refer to this list of global attributes in HTML5.

Events

Global events

For information about global events refer to this list of global events in HTML5.