← Back to HTML Course | Chapter 4: Semantics & Entities | Lesson 9 of 10

HTML Ruby Annotations

In East Asian typography, small pronunciation guides are often printed directly above or beside a character to help readers who might not know how to pronounce it -- Japanese furigana above kanji is the classic example. HTML has three dedicated elements just for this: ruby wraps the whole annotated unit, rt holds the pronunciation text, and rp provides a fallback for browsers that do not understand ruby annotations at all.

In this page:

  1. Wrapping a Base and Annotation with ruby
  2. Adding Pronunciation with rt
  3. Fallback Parentheses with rp
  4. Styling Ruby Text with CSS
  5. When to Use Ruby Annotations
Syntax
markup 
<ruby>
  base text <rp>(</rp><rt>annotation</rt><rp>)</rp>
</ruby>

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

markup 
<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

markup 
<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

markup 
<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

markup 
<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

markup 
<ruby>難<rt>nán</rt></ruby>
Live Example
Related Topics

HTML vs XHTML · HTML Heading Groups · HTML URL Encode · HTML Charsets

{# common_mistakes/chapter_summary/browser_support: on Hindi pages the view already swaps in the hi_ translation fields (or blanks these out if untranslated), so this renders correctly for both languages without a lang_code check here. #}
Common Mistakes
  1. 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.
  2. Using ruby purely for visual superscript-style annotations unrelated to pronunciation, when sup or a styled span is the more appropriate, lighter-weight choice.
  3. Nesting block-level elements inside rt, when rt is meant to hold only short inline pronunciation text.
Chapter Summary
  • 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.
Browser Support

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:

← Previous Lesson HTML vs XHTML Next Lesson → HTML Heading Groups

Login to run this code

C/C++/Java/PHP execution requires a free account. Your code is saved — you'll land right back in the editor after logging in.