How to Use CSS ruby-position for Ruby Text

The CSS ruby-position property controls the placement of phonetic annotations, known as ruby text, relative to their base characters in East Asian typography. In languages such as Japanese and Chinese, ruby annotations provide pronunciation guides—such as furigana, pinyin, or bopomofo—or contextual meanings alongside the primary text. This guide explains the functional values of ruby-position, how it interacts with different writing modes, and how to implement it to achieve correct typographical layout.

What is Ruby Text?

In East Asian web typography, ruby annotations are marked up using HTML elements: <ruby> wraps the entire construct, <rt> marks the ruby text (the annotation), and optional elements like <rp> provide fallbacks for unsupported browsers. By default, browsers place ruby annotations adjacent to the base characters according to standard typographical conventions, but the ruby-position property allows developers to alter this placement.

Core Syntax and Values

The ruby-position property is applied directly to the <ruby> container or its nested <rt> elements. It accepts several keyword values:

ruby {
  ruby-position: over;
}

1. over

This is the default value for standard horizontal text. It positions the ruby text above the base text in horizontal writing modes. When text is laid out vertically (such as Japanese vertical-right-to-left layout), over places the ruby text to the right of the base text, which corresponds to the typographical block-start side.

2. under

The under value positions the annotation below the base text in horizontal writing modes. In vertical layouts, it places the ruby text to the left of the base text (the block-end side).

This placement is common in:

• Educational Chinese texts: Where Pinyin annotations are positioned beneath Chinese characters to avoid colliding with other marks.
• Secondary Japanese annotations: Where complex literature uses simultaneous annotations, placing furigana (readings) above the text and definitions or translations below.

3. alternate

Defined in the CSS Ruby Annotation Layout module, alternate is designed for elements with multiple levels of annotations. When applied, it alternates the position of consecutive <rt> elements, rendering one above (over) and the next below (under).

4. inter-character

The inter-character value is specifically designed for Taiwanese Bopomofo (Zhuyin). When text is rendered vertically, Bopomofo tone marks and phonetic symbols must be laid out vertically alongside and between the base characters rather than strictly stacked as a standard block annotation. If used in horizontal text, standard user agents fall back to over.

Interaction with Writing Modes

The physical rendering of ruby-position depends directly on the CSS writing-mode property:

Because East Asian literature frequently transitions between horizontal and vertical layouts, using standard directional keywords ensures that annotations follow logical block axes without requiring layout-specific overrides.

Example Implementation

The following example demonstrates how to set ruby annotations below the base characters for a Chinese Pinyin guide:

<p>
  Learning Chinese: 
  <ruby class="pinyin-guide">
    漢 <rt>hàn</rt>
    語 <rt>yǔ</rt>
  </ruby>
</p>

.pinyin-guide {
  ruby-position: under;
  font-size: 1.5rem;
}

.pinyin-guide rt {
  font-size: 0.5em;
  color: #555;
}

In this setup, the phonetic readings hàn and yǔ appear directly underneath their respective characters rather than above them, improving readability for specific instructional designs.