<ruby> Ruby annotation
Small annotations above or beside text, mostly for East Asian pronunciation.
<ruby> puts small annotations next to base text. Most of the time they give the pronunciation of Chinese, Japanese or Korean characters. Inside the element, the base text comes first, followed by <rt> elements that hold the annotation.
Optional <rp> elements add fallback brackets for very old browsers that cannot display ruby. Every current browser supports it.
The ruby element in the HTML Living Standard (opens in a new tab) has detailed examples for Japanese and Chinese. The annotation itself lives in an rt element.
Syntax
<ruby>base<rt>annotation</rt></ruby>When to use it
<ruby> puts a reading aid right next to the text: furigana over kanji in Japanese learning materials or children's books, pinyin over Chinese characters, zhuyin in Taiwanese texts, or a pronunciation guide over a hard word in any language.
If the explanation can wait, a tooltip-style abbr or text in brackets is simpler. If you are teaching a term, dfn with a sentence is clearer. Choose ruby when the annotation must be visible at the same moment as the base text.
Decide how to group. Mono ruby gives each character its own rt; group ruby puts one rt over a whole word when the reading cannot be split by character. Some older guides use rb and rtc elements; those are obsolete in the Living Standard, so write the base text directly followed by rt. Ruby text also adds height above the line, so give such paragraphs a larger line-height.
Live example
Edit the code and watch the preview.
<p style="font-size:2em"><ruby>漢<rp>(</rp><rt>kan</rt><rp>)</rp>字<rp>(</rp><rt>ji</rt><rp>)</rp></ruby></p>More examples
Pinyin for Chinese
Each Chinese character gets its own pinyin reading in an rt element. The tone marks are written as numeric character references, and lang tells the browser the text is Chinese.
<p lang="zh" style="font-size:2em;line-height:2"><ruby>你<rt>nǐ</rt>好<rt>hǎo</rt></ruby></p>
<p>(Translation: hello)</p>Mono ruby versus group ruby
The Japanese word for Tokyo is annotated two ways. The first gives each character its own reading; the second places one reading over the whole word. rp adds brackets for browsers without ruby support.
<p lang="ja" style="font-size:2em;line-height:2"><ruby>東<rp>(</rp><rt>とう</rt><rp>)</rp>京<rp>(</rp><rt>きょう</rt><rp>)</rp></ruby></p>
<p lang="ja" style="font-size:2em;line-height:2"><ruby>東京<rp>(</rp><rt>とうきょう</rt><rp>)</rp></ruby></p>Tip: Each annotation goes in rt, right after its base text.
Browser support
Basic ruby with rt and rp works in all current browsers; Firefox added it in version 38. Finer layout control through CSS, such as ruby-position and ruby-align, is less consistent. Check the ruby annotation support table (opens in a new tab) before relying on advanced features.
Accessibility
Screen readers handle ruby unevenly and sometimes read both the base and the annotation. Set the correct lang attribute so the characters at least get pronounced properly. How lang affects pronunciation is explained in the W3C note Understanding Language of Parts (opens in a new tab).
Common mistakes
Wrong
<ruby><rt>kan</rt>漢</ruby>Right
<ruby>漢<rt>kan</rt></ruby>The rt annotation has to follow the base text it describes.
Frequently asked questions
What is ruby text in HTML?
Small runs of text placed above or beside base text, usually to show how East Asian characters are pronounced. Furigana in Japanese and pinyin in Chinese are the familiar examples. In HTML you wrap the base text in <ruby> and put each annotation in an <rt> element right after the characters it describes. Furigana and other uses are explained in Wikipedia's article on ruby characters (opens in a new tab).
Do I still need the rp tag?
Not really, but it does no harm. <rp> provides fallback parentheses for browsers without ruby support, so the annotation shows up as text in brackets. Every current browser supports ruby and hides rp content. It still keeps the text readable when it is copied or shown without CSS.