A site teaching Japanese displays a kanji followed by a small annotation positioned above it, smaller than the main text, giving its pronunciation in hiragana, so the reader can pronounce the word without already knowing the character.
<ruby> is the HTML container built for exactly this display: it groups the base text and its annotation into a single composition, with a clean fallback for browsers that cannot render it correctly.
Definition
<ruby> wraps a ruby composition: a base text accompanied by a short annotation, most often a pronunciation or a gloss, shown above it through <rt> nested inside. The name comes from print typography, where these small annotations already carried it well before the web existed.
The most cited use case is Japanese furigana: a kanji followed by its reading in hiragana, to help a beginner reader pronounce a character they do not yet recognise. The same mechanism also serves Chinese, Korean, or glossing a rare word in any language.
Structure: base, annotation and fallback
A full ruby composition combines three elements: the base text placed directly inside <ruby>, the annotation inside rt, and a pair of <rp> wrapping the annotation with fallback parentheses.
<ruby>
漢字
<rp>(</rp><rt>かんじ</rt><rp>)</rp>
</ruby>A browser that understands ruby ignores the parentheses inside rp and shows かんじ in small text, positioned above 漢字. A browser that does not understand it shows all the text in sequence, parentheses included, which stays readable even without any particular styling.
Semantics and accessibility
A ruby composition carries a precise meaning that a plain smaller text placed above with CSS alone would not: it explicitly links a base and its annotation, which assistive technology and machine translation tools can use to render both correctly, in the right order and with the right relationship between them.
A common trap is recreating a ruby effect visually with two positioned blocks in CSS, without using <ruby> or rt at all. The rendering can look identical on screen, but the relationship between the base text and its annotation disappears for anything that does not see the styling: screen readers, search engines, copying the text into an online translator.
Best practices
Always pairing <ruby> with rt for the annotation and a pair of rp for the fallback costs two extra small tags and secures the display on any browser, old or new. Testing the rendering without a ruby stylesheet stays the simplest way to check that an annotated text remains readable under any circumstance.
Use cases beyond Japanese
Furigana remains the most cited example, but <ruby> suits any short annotation tied to a precise word: a phonetic transcription in an online dictionary, a quick translation of a technical term the first time it appears in a text, or a grammatical gloss in a language-learning resource.
Believemy could, for instance, use it in a vocabulary lesson to show the pronunciation of an English word directly above its spelling, without weighing down the sentence with an explicit parenthesis.
Frequently asked questions
Does <ruby> work for languages other than Japanese?
Yes, nothing in the specification limits it to Japanese. It is also commonly used for Chinese and Korean, and remains perfectly valid for glossing a rare word in French or English with its pronunciation or a short translation, whenever an annotation needs to stay attached to a precise word.
What happens if rt is used without <ruby> around it?
Technically the text still displays, but the relationship between the annotation and its base disappears: the browser no longer knows which exact word to attach the pronunciation to. <ruby> is the container that gives <rt> its meaning, not a simple optional visual wrapper around it.
Do the parentheses from rp show up in modern browsers?
No, on a browser that correctly supports ruby, their content stays invisible on screen: the browser already knows how to position the annotation in the right place and needs no parentheses at all. They only reappear in the rare browsers unable to render a ruby composition correctly.