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 .
| 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!
32 Responses on the article “The ruby element and her hawt friends, rt and rp”
[…] This post was mentioned on Twitter by bruce lawson, 윤석찬(Channy Yun), Rich_Clark, Oli Studholme, html5 gallery and others. html5 gallery said: Ruby, rt & rp in #html5 from our friends over @html5doctor http://html5doctor.com/ruby-rt-rp-element/ […]
Dear HTML5 book writers, you’re welcome ;-)
[…] This post was mentioned on Twitter by Ânderson Quadros. Ânderson Quadros said: Ruby & HTML5: http://bit.ly/dB8kN8 #ruby #html5 (via @html5doctor) […]
In case anyone else was wondering.. I had to know why it’s called ruby…
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.
Can it be used to markup guitar chords over lyrics?
@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!)
It’s useful for annotation , thans for share.
The just-announced Safari 5 supports
<ruby>too! Yay! Added to support table…Great article, keep up the good work.
Bonus for source readers :-)
[…] more about ruby’s implementation in HTML or just to track browser compatibility over time, this article on Html5doctor.com is great reading! […]
Detecting
<ruby>is in the Modernizr feature request list, so the Modernizr team may add support for it at some stage. This would let us do a lot more styling of ruby text in non-supporting browsers, without messing things up for supporting browsers. Thanks and 宜しく @paul_irish! :)Большое спасибо за информацию.
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!
Your example for pinyin is either very audacious or in very poor taste. I just don’t know about it…
@Trevor — Grass Mud Horse context, so probably a little of both ;) Plenty of in-jokes around here, for the observant…
Hi,
Do you mean the bopomofo in the following image is ‘incorrect’?
http://html5doctor.com/wp-content/uploads/2010/05/bopomofo-chrome.png
May I ask which part is incorrect and which browser were used to render this?
I copy the script to my IE8 and get the following result.
http://tinyurl.com/23qn3xc
Thanks
@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.
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.
[…] For detailed information on its usage I highly recommend the related HTML5 Doctor article. […]
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.
@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>The ‘Grass mud horse’ example is sneaky ;-)
@Shi Chuan — we try to include a little sneak wherever possible, for your reading pleasure ;) ;)
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.
@Will — It seems you missed the “These code samples (with notes and CSS) are also available separately” bit. Apologies for my laziness, I really should go through and individually link each example.
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!
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.
Modernizr has added a feature detect for
<ruby>. Thanks Alrra!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>
I like to use ruby any time I want to use a foreign word inline and provide a translation:
I love to eat <ruby lang="kr">김치 <rp>(</rp><rt lang="en-us">kimchi</rt><rp>)</rp></ruby>Hi, I’ve just started using ruby for transliterating Javanese script, and it looks good. I was looking for a way to display the transliteration on the bottom, to no avail. Here’s a sample text:
꧅ꦚ꧀ꦖ꧅ ꦩꦔꦺꦱ꧀ꦛꦶꦮꦿꦸꦃꦱꦿꦶꦫꦺꦁꦲꦾꦁꦄꦂꦠꦠꦶ꧈1. Mangèsthi wruh srirèng Hyang Artati
They should make tag for ruby-bottom, to supplement “rt” for ruby-top
Join the discussion.