Skip to content
Tutorials Center
My learning

Topics

HTML Reference Β· Inline Text

The <ruby> element

Reference for the HTML <ruby> element: small pronunciation or meaning notes above East Asian characters, with <rt> and <rp>, examples and technical details.

The <ruby> element pairs base text with a small annotation that the browser shows above it (or beside it in vertical writing). It is named after "ruby" type, an old printing term for very small text. Its most common use is showing how to read Chinese characters or Japanese kanji, but it works for any short gloss, such as a translation or a phonetic spelling.

Inside <ruby>, you write the base text and follow it with an <rt> element holding the annotation. Optional <rp> elements add fallback parentheses for browsers that cannot render ruby.

HTML
<ruby>東京<rp>(</rp><rt>とうきょう</rt><rp>)</rp></ruby>

Try it

Ruby annotations

In the first example each character gets its own reading, because every base character is followed by its own <rt>. In the second, one annotation covers the whole word.

Attributes

This element has no attributes of its own. It accepts the global attributes. Setting lang (for example lang="ja") helps browsers pick a suitable font and line-breaking rules.

Usage notes

  • Pattern. Base text, then <rt>; repeat the pair for per-character annotations. Wrap optional <rp> parentheses around each <rt>.
  • Keep annotations short. Ruby text is rendered at roughly half the base size. Long glosses become hard to read and stretch the line; use a footnote or a <dfn> definition instead.
  • Position. CSS ruby-position moves annotations below the base (under) or back to the default (over). In vertical text they appear to the side.
  • Accessibility. Screen readers handle ruby inconsistently: some read both the base and the annotation, some only one. Don't put information only in the <rt> if it is essential to understanding the sentence.
  • Older <rb> and <rtc>. These elements once marked base segments and annotation containers. They are obsolete in the WHATWG standard; write base text directly inside <ruby>.

Technical summary

Content categories Flow content, phrasing content, palpable content
Permitted content Base text (phrasing content without <ruby> descendants, or a single nested <ruby>) followed by one or more <rt> elements, each optionally surrounded by <rp> elements; the base-plus-annotation group can repeat
Tag omission None; both the start and end tags are required
Permitted parents Any element that accepts phrasing content
Implicit ARIA role No corresponding role
DOM interface HTMLElement
Default display ruby

Browser support

Supported in all current browsers; the CSS ruby layout model used for fine-tuning (such as ruby-align) has less consistent support than the element itself.