Ruby text is a short annotation for some base text. It’s typically used to give pronunciation guidance in a phonetic script for kanji in Chinese, Japanese, and Korean (CJK) languages. It’s named after an old printers’ term for the very small size of 5.5 points.
The ruby element allows spans of phrasing content to be marked with ruby annotations.
W3C Specification
As the name implies, ruby text is small, displayed by default above the base text in horizontal text and to the right in vertical text. Browsers without <ruby> support put the ruby text inline after the base text.
These are the elements used in creating ruby text in HTML5:
<ruby>— an inline element that contains base text with ruby annotations<rt>— ruby text, coming after the base text it defines<rp>— ruby parentheses, an element used to wrap opening and closing parentheses around<rt>ruby text. These are for user agents that don’t support ruby text, so that it makes sense when displayed inline. Browsers that support<ruby>hide<rp>via{display:none;}.
Examples
If you’ve never seen ruby in action you’re probably wondering what I’m talking about, so here are some examples:
Browser support
As is often the way with internationalisation features, browser support is — well, sparse. In a break from your expectations, Internet Explorer has supported <ruby> since IE5 — three years before the actual 2001 W3C Ruby Annotation specification! While this specification was incorporated into XHTML 1.1, no browser ever implemented it.
<ruby> in HTML5 is based on a reverse-engineering of IE’s implementation. It also lacks Ruby Annotation’s ‘complex <ruby>’, as these can normally be accomplished via nesting. (Please submit feedback if you have a real-world example that can’t be.) Webkit added HTML5 <ruby> support at the start of 2010. At the time of writing, <ruby> has made it into Chrome but not Safari. Firefox and Opera have yet to implement <ruby> natively, although there are Firefox extensions for <ruby> support (HTML Ruby (basic ruby including HTML5) and XHTML Ruby (complex ruby)).
On the styling side, there’s the W3C CSS3 Ruby Module (2003). It’s based on Ruby Annotation’s ‘complex ruby’ and is being updated for HTML5 <ruby>. Because of this, it’s also yet to be implemented beyond the default IE-level formatting. Ruby text will be used in combination with the W3C CSS Text Layout Module Level 3 properties direction, block-flow, and writing-mode for alternative text flow (such as vertical text), but again these have poor implementation.
| Browser | Basic <ruby> |
writing-mode |
‘Complex <ruby>’ |
CSS3 Ruby (2003) |
|---|---|---|---|---|
| Internet Explorer | IE5.5+ | IE6+* | - | - |
| Firefox | (via plugin) | - | (via plugin) | - |
| Chrome | Chrome5+ | - | - | - |
| Safari | Safari5+ | - | - | - |
| Opera | - | - | - | - |
Note: writing-mode support in IE6 was lr-tb and tb-rl only. IE8 added support for all possible combinations.
CSS we can use
Having said that no browsers support the CSS3 Ruby module yet, there are still a few things we can do to style <ruby> and friends. Default browser styles use font-size and display, so we can safely change these to affect display in both supporting and non-supporting browsers.
If you want to de-emphasise the <rt> ruby text when it’s displayed inline in non-supporting browsers, you could do this via setting the size of <rt> and <rp>, as IE and Webkit do:
rt, rp {font-size: 60%;} /* = Webkit value */You can also move ruby text and parentheses to after the base text, mimicking non-supporting browser rendering on supporting browsers:
rt, rp {display: inline; font-size: 100%;}Finally, if you’re brave/foolish, you can implement ruby display yourself via CSS inline-table (CSS with explanation and demonstration (Hiragana.jp)). Note that this currently doesn’t work in Chrome because of a bug with display:inline-table on <ruby> (fixed in trunk), and as you’ll probably need per-browser style tweaks, I recommend against it.
Code samples and output
These code samples (with notes and CSS) are also available separately.
<ruby> in Japanese — furigana and rōmaji
Using <ruby> without <rp>
<ruby>攻殻<rt>こうかく</rt>機動隊<rt>きどうたい</rt></ruby>
<ruby> to indicate the pronunciation of the Japanese name of the Ghost in the Shell anime series in furigana. Notice that the lack of <rp> makes it pretty unreadable in a non-supporting browser (you may have to trust me on this!).Using <ruby> with <rp>
<ruby>攻殻<rp>（</rp><rt>こうかく</rt><rp>）</rp>機動隊<rp>（</rp><rt>きどうたい</rt><rp>）</rp></ruby>
<rt> text surrounded by <rp> parentheses degrades gracefully on non-supporting browsers.Nested <ruby> for multiple ruby texts
<ruby><ruby>攻<rp>（</rp><rt>こう</rt><rp>）</rp>殻<rp>（</rp><rt>かく</rt><rp>）</rp>機<rp>（</rp><rt>き</rt><rp>）</rp>動<rp>（</rp><rt>どう</rt><rp>）</rp>隊<rp>（</rp><rt>たい</rt><rp>）</rp></ruby><rp>（</rp><rt>Kōkakukidōtai</rt><rp>）</rp></ruby>
<rt> depends on the amount of base text before it, from one character to an entire phrase. <ruby> can also be nested to provide multiple ruby texts for one base text — in this case furigana and rōmaji. Although per-kanji <ruby> is more informative, it degrades somewhat poorly in non-supporting browsers. Copy & paste support is also poor, as browsers just use source order, for example “攻こう殻かく機き動どう隊たい Kōkakukidōtai”. It’s also a PITA to code 
<ruby> in Chinese — Pīnyīn and zhùyīn fúhào (bopomofo)
Ruby is used to some extent in China (pīnyīn), and more so in Taiwan (zhùyīn fúhào), especially in textbooks and signage.
Pīnyīn
<p>The <b>Grass mud horse</b> — <ruby>草泥馬<rp>(</rp><rt>Cǎo Ní Mǎ</rt><rp>)</rp></ruby> — is … characterised as “lively, intelligent and tenacious”. However, their existence is said to be threatened by the “river crabs” — <ruby class="styled">河蟹<rp> (</rp><rt>héxiè</rt><rp>) </rp></ruby> — which are invading their habitat.</p>
<ruby> significantly affects the leading (<line-height>) of text blocks in supporting browsers. Setting font-size for <rt> and <rp> can de-emphasise ruby text in non-supporting browsers, as demonstrated in the second <ruby> in the second image.Zhùyīn fúhào
<ruby><ruby>世<rp>（</rp><rt>ㄕˋ</rt><rp>）</rp>上<rp>（</rp><rt>ㄕㄤˋ</rt><rp>）</rp>無<rp>（</rp><rt>ㄨˊ</rt><rp>）</rp>難<rp>（</rp><rt>ㄋㄢˊ</rt><rp>）</rp>事<rp>（</rp><rt>ㄕˋ</rt><rp>）</rp>只<rp>（</rp><rt>ㄓˇ</rt><rp>）</rp>怕<rp>（</rp><rt>ㄆㄚˋ</rt><rp>）</rp>有<rp>（</rp><rt>ㄧㄡˇ</rt><rp>）</rp>心<rp>（</rp><rt>ㄒㄧㄣ</rt><rp>）</rp>人<rp>（</rp><rt>ㄖㄣˊ</rt><rp>）</rp></ruby><rp> （</rp><rt>Anything can be done with enough perseverance</rt><rp>）</rp></ruby>
Chinese glossary
Pīnyīn is a romanised phonetic system for Chinese, generally written above or after the word. Bopomofo (Zhùyīn fúhào) is a phonetic script for transcribing Chinese, especially Mandarin. It is generally written (in both horizontal and vertical scripts) vertically to the right of each hanzi character.
Korean ruby
While the use of hanja (kanji) is decreasing in South Korea, they are still used for disambiguation and proper names.
<ruby>한자<rp>(</rp><rt>漢字</rt><rp>)</rp></ruby>
rt, rp {display: inline; font-size: 100%;}. This formatting is also used when foreign words such as English are included in Korean text.Korean glossary
Hangul is the Korean script, and hanja is Korean for Chinese characters. Traditionally written Korean used hanja, but now it’s mainly used in academic texts and occasionally for disambiguation.
Using <ruby> for English
Not everyone is using East Asian languages, but any short annotation is (theoretically) applicable. While English doesn’t typically have pronunciation guidance, phonetic annotations are used in dictionaries:
<ruby><strong>cromulent</strong> <rp>(</rp><rt>crôm-yü-lənt</rt><rp>)</rp></ruby>
<ruby>: to use or not to use
The main use case of <ruby> is marking up pronunciation in Asian writing, such as bopomofo for traditional Chinese and furigana for Japanese. I don’t know whether Arabic diacritics like Taškīl, Hebrew Niqqud, or other non-CJK languages would use <ruby> for marking up phonetic annotations or diacritics. The WHATWG specification says:
Ruby annotations are short runs of text presented alongside base text, primarily used in East Asian typography as a guide for pronunciation or to include other annotations
As someone who uses tools like Popjisyo to add pop-up readings and translations to kanji, I definitely see <ruby> as semantic (and valuable) for ‘phonetic annotation,’ in the same way that <abbr> provides extra information on potentially confusing content. Outside of this usage, however, <ruby> could be seen as a presentational hack. Oh noes! I believe the Korean and English examples above are valid uses, but much like <q> some people think the extra code of using <ruby> is not justified when the default presentation is the same as plain text.
To further muddy the waters, the 2001 W3 Ruby specification included an abbreviated word marked up with a visible definition via <ruby>, and a use-by date where the day, month, and year are added via <ruby>. These uses seem like presentational hacks to me, and while they’re not forbidden, the lack of such examples in HTML5 indicate they’re not exactly blessed either 
In conclusion…
The most important thing is that the <ruby>, <rt>, and <rp> elements are valid HTML5, and even if they’re not officially supported, they will by default display as if they were <span>s in non-supporting browsers. Because of this, if you actually need to use <ruby>, especially for phonetic annotations, do it! It might not look perfect yet in non-supporting browsers, but this will change, and hey, at least you don’t have IE support to worry about!
For non-phonetic annotation, consider using <abbr> to give an expanded reading via mouse-over for an abbreviation or acronym, unless displaying the reading by default is important. Consider <small> for phrasing content-level side comments, if the comment placement is not important and the association with the relevant content doesn’t need to be explicit.
Further reading
- Ruby rendering in Webkit announcement on the Safari weblog
- The HTML5 <ruby> element in words of one syllable or less by the unstoppable Daniel Davis of Opera
Feedback please!
So what do you think of <ruby> and friends? Let us know in the comments! If you know about the use of annotations like this in other languages, or have used <ruby>, tell us about it too!
