ruby
Represents a ruby annotation, used for East Asian typography to show pronunciation guides above or beside base text.
Description
The <ruby> element represents a ruby annotation — small text above or beside base text, typically showing pronunciation. Ruby annotations are essential for East Asian typography (furigana in Japanese, pinyin in Chinese) but can also help with pronunciation guides in any language.
A ruby annotation consists of base text, ruby text (<rt>), and optional fallback parentheses (<rp>).
VB provides i18n-aware styling: CJK script fonts for ruby text, and a data-ruby visibility system to control when annotations appear.
When to Use
- Japanese furigana: Pronunciation guides for kanji
- Chinese pinyin: Romanized pronunciation for Chinese characters
- Korean: Hanja pronunciation guides
- Language learning: Pronunciation for unfamiliar words in any language
- Accessibility: Helping users with reading difficulties
Examples
<p> <ruby>東京<rp>(</rp><rt>とうきょう</rt><rp>)</rp></ruby>は日本の首都です。</p><p> <ruby>北京<rp>(</rp><rt>Běijīng</rt><rp>)</rp></ruby> is the capital of China.</p><ruby> 漢 <rp>(</rp><rt>かん</rt><rp>)</rp> 字 <rp>(</rp><rt>じ</rt><rp>)</rp></ruby><p> How to pronounce <ruby>Versailles<rp>(</rp><rt>vair-SIGH</rt><rp>)</rp></ruby>.</p>Ruby Visibility Control
VB's i18n system provides a data-ruby attribute on <html> to control when annotations display:
| Value | Behavior |
|---|---|
show |
Always visible |
hide |
Visually hidden, kept in DOM for screen readers |
auto |
Visible for CJK languages (ja, zh, ko), hidden otherwise |
| (absent) | Browser default (always visible) |
<html lang="ja" data-ruby="auto"><body> <!-- Ruby visible (CJK language) --> <ruby>漢字<rt>かんじ</rt></ruby> <section lang="en"> <!-- Ruby hidden (non-CJK) --> <ruby>ruby<rt>annotation</rt></ruby> </section></body></html>/* data-ruby="show" — always visible */:root[data-ruby="show"] rt { display: block; } /* data-ruby="hide" — visually hidden, accessible */:root[data-ruby="hide"] rt { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0,0,0,0);} /* data-ruby="auto" — visible for CJK only */:root[data-ruby="auto"] rt { /* hidden by default */ }:root[data-ruby="auto"]:lang(ja) rt,:root[data-ruby="auto"]:lang(zh) rt,:root[data-ruby="auto"]:lang(ko) rt { /* shown */ }CSS Reference
ruby { display: ruby;} rt { font-size: 0.5em; line-height: 1; ruby-align: center;} rp { display: none; /* hidden in supporting browsers */}Styling Options
| Property | Effect |
|---|---|
ruby-position: over |
Annotation above base text (default) |
ruby-position: under |
Annotation below base text |
ruby-align: center |
Center annotation over base text (VB default) |
rt font-size |
0.5em (VB default) |
Accessibility
- Screen readers may read both base text and ruby text, or provide options for users to hear annotations
- The
<rp>fallback ensures annotations appear in parentheses when ruby is not supported - Ruby text benefits language learners and those with reading difficulties
- The
data-ruby="hide"mode keeps annotations in the DOM for accessibility even when visually hidden
Related
<rt>— The ruby text (annotation content)<rp>— Fallback parentheses for non-supporting browsers<bdi>— Bidirectional isolation for mixed-script text<bdo>— Bidirectional direction override- Internationalization guide — Script-specific typography, ruby visibility, locale quotes
Browser Support
Ruby annotations are supported in all modern browsers. The ruby-position CSS property is supported in Chrome, Edge, Safari, and Firefox 38+.