The ruby element and her hawt friends, rt and rp

by .

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:

Vagabond
Furigana ruby text in the Japanese manga Vagabond
Bopomofo Newspaper
Snippet of a Taiwanese newspaper for students, with bopomofo ruby
Typical Korean usage of hanji in a Korean news website
Korean hangul followed by hanja in an editorial on Chosun.com

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.

Summary of browser support for <ruby> display & styling in the five main browsers
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>
Furigana example using ruby in a supporting browser (displayed above base text) Furigana example using ruby in a non-supporting browser (displayed inline after base text)
Using <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>
Furigana example using ruby in a supporting browser (displayed above base text) Furigana example using ruby in a non-supporting browser (displayed inline with parentheses)
The above example with <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>
Two ruby texts in a supporting browser (both displayed above base text) Two ruby texts in a non-supporting browser (displayed inline in source order)
The scope of <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 :-|

Japanese glossary

Furigana is the name given to using hiragana phonetic script beside words written in kanji to aid reading. It’s used extensively in education for learners of Japanese, and in reading material for children. It’s also sometimes used when writing kanji a literate adult may not be able to read.

Rōmaji is the romanisation of Japanese into the latin alphabet. Rōmaji is generally used for those who don’t know Japanese, especially in signage and tourism information.

<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 text in a paragraph of text in a supporting browser, leading to significant line-height differences Ruby text in a non-supporting browser, with font-size set on rt and rp elements for the second ruby instance
In this example of pinyin you can see how <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>
How this bopomofo *should* look in a supporting browser (which doesn’t exist as far as I know) This bopomofo example in Chrome This bopomofo example in Firefox
Unfortunately, no browser can render this example of Zhùyīn fúhào (bopomofo) ruby on horizontal Mandarin Chinese correctly. I’ve included an ideal rendering and how it appears in both a browser supporting simple ruby (with incorrectly rendered bopomofo) and a non-supporting browser.

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>
Hangul followed inline by hanja in brackets
Current Korean ruby use is to have the hangul coming before the hanja in parentheses (the opposite way from the default fallback style). For styling use: 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>
Displaying ruby text after the base text for an English dictionary
Using ruby text for a dictionary definition by displaying the ruby text inline after the base text

<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

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!

30 Responses on the article “The ruby element and her hawt friends, rt and rp”

Oli Studholme says

Dear HTML5 book writers, you’re welcome ;-)

Paul Irish says

In case anyone else was wondering.. I had to know why it’s called ruby

In British typography, ruby was originally the name for type with a height of 5.5 points, used for interlinear annotations in printed documents. In Japanese, rather than referring to the name of a font size, the word came to refer to typeset furigana. When transliterated back into English, the word was rendered in some texts as “rubi” (the typical romanization of the Japanese word ルビ). However, the spelling “ruby” has become more common since a W3C recommendation for ruby markup was published.

Stuart Frisby says

This is brilliant. I’ve been playing around with various incarnations of Ruby text in browsers for years, from firefox plugins and horrible hackish CSS to javascript based nastiness which always seemed to go firmly against the grain of producing nice, clean, readable code. You wouldn’t believe how badly this has been needed for a very long time. Lets hope the browser vendors jump on this in an official manner, and that we can start presenting furigana properly and usefully before too long.

As an aside, I have long believed that the dominance of flash in Japanese web design has been largely down to the sub-standard provisions made for the Japanese language in HTML. Maybe this is indicative of a shift in that policy, and in turn will perhaps help makers of Japanese language websites to ween themselves off of the flash stuff a little.

Andrés Sanhueza says

Can it be used to markup guitar chords over lyrics?

Oli Studholme says

@Paul Irish — I see you followed the first link ;-)

@Stuart Frisby — It’s a sad state of affairs isn’t it. The 10 year anniversary of the Mozilla “implement <ruby> support” bug was two months ago. Don’t give up <ruby>, you can do it! Ganbare!

While I agree that browser implementation of HTML’s internationalisation features (such as <ruby>) has been painfully slow, I think the main reasons are elsewhere. Default Japanese text rendering generally looks pretty bad on Windows. In addition to more control over rendering, Flash tools are in Japanese. Here’s hoping the CSS3 Ruby module will also get some lovin’ one day soon.

@Andrés Sanhueza — No. See Lilypond, which uses ASCII-based source, can output SVG and PDF, and seems to have the mindshare for music notation. Oh, it’s free too. Read Designing notation software: how not to do it for Lilypond’s take on why music notation in XML isn’t a good idea.

Update: Music notation with HTML5 canvas (should be SVG and not yet released, but looks promising!)

pengkai says

It’s useful for annotation , thans for share.

Bart says

Great article, keep up the good work.
Bonus for source readers :-)

Chendev says

Большое спасибо за информацию.

delphiki says

Thanks for clarifying me on this.
I encountered the ruby tag in here, but didn’t know what it was doing.

Thanks for the explanations!

Trevor says

Your example for pinyin is either very audacious or in very poor taste. I just don’t know about it…

Oli Studholme says

@Alvin — Bopomofo ruby should be displayed vertically beside each hanzi character, as in the first of the three images. There are two problems with my sample image: bopomofo are above the hanzi, and the horizontal line bopomofo characters have become vertical. In your example the bopomofo are still above the hanzi (not beside each hanzi character), and in addition the nested ruby (the English text) is after (rather than above).

For more detail have a look at the background information and live examples of ruby page I made.

Alvin says

Hi

I agreed that bopomofo is not well supported by browsers. We gotta do something for it.

But I want to clarify 2 things. According to the government endorsed standard (from http://www.edu.tw)

1. bopomofo can be above ‘OR’ beside hanzi.
2. The horizontal line bopomofo characters, “一”, SHOULD become vertical when writing bopomofo horizontally.
Please check this, writing bopomofo horizontally, and this, writing bopomofo vertically.

David Matthews says

I’m sorry, maybe it’s just me, but I still don’t understand the ruby tags. Could you try to explain it again? I’m honestly not trying to cause drama; the spec didn’t clear the tags up for me and nor did your explanation, but I am desperate to understand.

Oli Studholme says

@Alvin — thanks for your input, I’ll investigate further and update the article.

@David Matthews — <ruby>This is the ruby base text<rt>This is the ruby text</rt></ruby>

Shi Chuan says

The ‘Grass mud horse’ example is sneaky ;-)

Oli Studholme says

@Shi Chuan — we try to include a little sneak wherever possible, for your reading pleasure ;) ;)

Will Holcomb says

It would be nice if you had included your ruby snippets in the document so the reader can see how they render in their browser. It saves having to copy it to a renderer.

Oli Studholme says

Fantasai of CSS Working Group fame has written “Towards a Unified Ruby Model”. It’s an awesome overview of current and potential future ruby support, discussing complex ruby, and how to address jukugo ruby and double ruby. Definitely worth a read!

sgeos says

I think everything in my ruby and rt tags are not getting properly marked up with CSS in Safari. =) It looks like the drop shadow is being properly applied to the non-rt text.

elmimmo says

So, how does one use ruby text for text on an SVG path in an HTML5 document? I tried the following in Safari 5.1.7 & Chrome 19, but the curviness of the text breaks as soon as it hits the ruby tag.


<svg viewBox="0 0 368 189" width="368px" height="189px">
<path id="text1" fill="none" stroke="none" d="M0,91.136c139.857,10.762,213.495-144.318,368.003,9.474"/>
<text>
<textPath xlink:href="#text1">
<tspan>おはようございま〜す!<ruby>中<rt>なか</rt>中<rt>やま</rt></ruby>と申します。</tspan>
</textPath>
</text>
<path id="text2" fill="none" stroke="none" d="M1.312,125.111c159.488,8.086,230.681-109.674,366.521,54.255"/>
<text>
<textPath xlink:href="#text2">
<tspan>SVGでふりがなを使えないのは寂しいです。</tspan>
</textPath>
</text>
</svg>

Join the discussion.

Some HTML is ok

You can use these tags:
<a href="" title="">
<abbr title="">
<b>
<blockquote cite="">
<cite>
<del datetime="">
<em>
<i>
<q cite="">
<strong>

You can also use <code>, and remember to use &lt; and &gt; for brackets.