The CSS ruby-position Property

Overview

The ruby-position property determines the placement of a ruby element with respect to its base text. Ruby annotation is typically used in certain typography (primarily East Asian) to provide a short annotation or guide for pronunciation and other aspects. The position of this annotation can be adjusted with ruby-position to fit the typographical rules and reading direction of the language.

Examples and Usage

Below, we'll examine the usage of ruby-position with a ruby annotation. Our example includes Japanese text annotated with its pronunciation. Specifically, we'll demonstrate the behavior of the over and under values of the property. Keep in mind that this is purely for illustrative purposes.

HTML Structure

<ruby>
<!-- The base text-->
今日 <rp>(</rp><rt>Kyō</rt><rp>)</rp>
</ruby>

In our HTML, the <ruby> element encapsulates a phrase in Japanese text 今日, meaning "today" in English.

The <rt> element is used to specify the ruby annotation. Here, it provides the pronunciation of Kyō for the base text.
The <rp> element is used to show parentheses around the annotation. These parentheses serve a fallback function; they will be displayed in browsers that do not support ruby annotations. This allows users to see the pronunciation guide even if their browser does not support the ruby annotation.

CSS Styling

ruby {
  /* Setting up the size of the text for better visibility */
  font-size: 32px;
  /* Positioning the ruby annotation over the base text */
  ruby-position: over;
}

In the CSS setup, we increase the font-size for better visibility. The crucial aspect here, ruby-position, is set to over. This instructs the browser to position the ruby annotation Kyō above the base text 今日.

If we were to change the ruby-position value to under, as follows:

ruby {
  /* Positioning the ruby annotation under the base text */
  ruby-position:  under;
}

The ruby annotation Kyō would now appear below the base text 今日.

Values

Value	Description
`over`	Positions the ruby annotation above the base text for horizontal scripts, and to its right for vertical scripts.
`under`	Positions the ruby annotation below the base text for horizontal scripts, and to its left for vertical scripts.

Note: Two additional values, inter-character and alternate, are experimental and subject to change in future specifications. They currently have little to no browser support.

Associated Properties

ruby-align (experimental)

Tips and Tricks

ruby-position is most useful when designing for East Asian languages, as it allows you to adjust the position of pronunciation guides according to the language's specific typographic rules.
As the ruby annotation system is primarily used in East Asian languages, it's important to be mindful of language directionality when using ruby-position.
The usage of the under value is somewhat rare and it's mostly found in educational texts for ideographic East Asian writing systems.
Make use of the HTML element <rp> as a fallback for users whose browsers do not support ruby annotations. This ensures that they are still able to see the annotation text.

Browser Compatibility

For a detailed breakdown of implementation with vendor prefixes for specific browser versions, and support of the respective values, refer to the first link in the Useful Resources below.

Browser	Chrome	Edge	Safari	Firefox	Opera	Internet Explorer
Support	Yes*	Yes*	Yes*	Yes*	Yes*	No

Caution: Internet Explorer support data may be incorrect since MDN browser-compat-data no longer updates it. Also, early Edge versions used EdgeHTML, leading to mismatched version numbers. From version 79, Edge uses Chromium with matching version numbers.