HTML Ruby Annotations
In this page:
Wrapping a Base and Annotation with ruby
The ruby element wraps together a piece of base text (like a Japanese kanji character) and its ruby-supporting annotation (like the pronunciation), telling the browser these two pieces belong together as a single annotated unit that should render close to one another.
Note: Keep each ruby element focused on one small unit of text (a single word or character), rather than wrapping an entire sentence in one ruby block.
Warning: ruby alone, without an inner rt element, has nothing to actually display as the annotation -- the two elements work together, not separately.
Example: Wrapping a Base and Annotation with ruby
<ruby>漢<rt>kan</rt></ruby>Adding Pronunciation with rt
The rt (ruby text) element holds the actual annotation content -- typically the pronunciation or reading -- and browsers automatically render it smaller and positioned above the base text it annotates, without needing any extra CSS.
Note: Keep rt content short; ruby annotations are designed for brief pronunciation guides, not long explanatory text.
Warning: rt must be a direct child of ruby to render correctly as an annotation; placing it elsewhere has no special ruby styling effect.
Example: Adding Pronunciation with rt
<ruby>
漢 <rt>kan</rt>
字 <rt>ji</rt>
</ruby>Fallback Parentheses with rp
The rp (ruby parenthesis) element provides fallback content -- typically an opening and closing parenthesis -- that only displays in browsers without ruby support. Browsers that do support ruby annotations automatically hide the rp content, so it never causes visual duplication in modern browsers.
Note: Always include rp fallback parentheses around your rt content; the extra markup costs nothing in modern browsers and protects readability in older ones.
Warning: Without rp, a non-ruby-aware browser will run the base text and the annotation text together with no visual separation at all, making it hard to read.
Example: Fallback Parentheses with rp
<ruby>
漢<rp>(</rp><rt>kan</rt><rp>)</rp>
</ruby>Styling Ruby Text with CSS
ruby-position and ruby-align are CSS properties that let you control where the annotation sits (over, under, or beside the base text) and how it aligns, giving some visual control beyond the browser's automatic default placement above the base text.
Note: Leave ruby-position at its default in most cases -- above-the-text placement is what readers of annotated languages expect and recognize instantly.
Warning: CSS control over ruby styling is more limited and has patchier cross-browser support than most other text CSS properties, so test any custom ruby styling carefully.
Example: Styling Ruby Text with CSS
<style>
rt {
ruby-position: under;
}
</style>
<ruby>漢<rt>kan</rt></ruby>When to Use Ruby Annotations
Ruby annotations are purpose-built for East Asian pronunciation guides, but the same mechanism can annotate any base text with a short gloss -- like showing a word's definition or a difficult name's pronunciation in any language -- whenever you need a small annotation to sit directly attached to specific text rather than in a separate tooltip or footnote.
Note: Reach for ruby whenever an annotation needs to stay visually attached to specific inline text; use a title attribute or tooltip instead for longer, optional explanations.
Warning: Overusing ruby annotations on text that is not actually East Asian pronunciation-related can confuse readers and screen readers that expect ruby to mean "reading guide".
Example: When to Use Ruby Annotations
<ruby>難<rt>nán</rt></ruby>- Forgetting the rp fallback parentheses, which means very old or non-ruby-aware browsers will run the base text and pronunciation together with no visual separation.
- Using ruby purely for visual superscript-style annotations unrelated to pronunciation, when sup or a styled span is the more appropriate, lighter-weight choice.
- Nesting block-level elements inside rt, when rt is meant to hold only short inline pronunciation text.
- ruby wraps a base text unit together with its annotation, most commonly used for East Asian pronunciation guides like Japanese furigana.
- rt holds the actual annotation text, rendered smaller and above (or beside) the base text by browsers that support ruby.
- rp provides fallback parentheses shown only in browsers without ruby support, keeping the annotation readable everywhere.
ruby, rt, and rp are supported in all modern browsers, including Chrome, Firefox, Safari, and Edge; support has been solid since the mid-2010s.
Chapter Quiz — Complete all 10 topics to unlock
0/10 topics done
Complete these topics first: