HTML Ruby Tag: Syntax & Usage Guide

Are you trying to display Japanese, Chinese, or Korean text on your website but struggling to show how those characters should be pronounced? For many developers, formatting East Asian typography is a significant challenge.

Without the right markup, adding small phonetic guides (known as <ruby> characters) can look messy or break your layout. The HTML <ruby> tag is the official web standard that was made to fix this problem. In this article, we will go over the syntax, look at real-world examples, and show you how to use this tag to improve your web applications.

What is the HTML <ruby> Tag?

It is a container that holds base text along with a small annotation or pronunciation guide, commonly used in East Asian languages.

The <ruby> tag tells the browser to treat the base text and the annotation as one piece of text. The browser then takes care of the placement, which is usually putting the annotation in a smaller font just over the base text.

<ruby> Markup Elements:

You need to know how the <ruby> tag works with two additional nested tags in order to use it correctly:

rt (<ruby> Text): This tag has the genuine meaning or phonetic characters, like Hiragana or Pinyin.
rp (<ruby> Parentheses): This tag gives browsers that don’t support <ruby> annotations a way to use parentheses instead. It hides the parentheses in modern browsers but shows them in older ones, making the text still easy to read.
rb (<ruby> Base): This tag tells you what the base text is in a <ruby> annotation. In simple cases, it’s not required, but it can be helpful when several annotations are used in more complex structures.

HTML <ruby> Tag Syntax

This tag has a simple structure, but it needs to be nested in a certain way to work right. This is the basic format for <ruby> tags that you should use:

HTML

<<ruby>>
Base Character
<rp>(</rp>
<rt>Annotation Text</rt>
<rp>)</rp>
</<ruby>>

The <ruby> tag is the parent in this hierarchy. The base character is what the user sees, and the rt tag tells them what to do. The rp tags are optional but highly recommended for better compatibility.

HTML <ruby> Tag Example

Let’s look at a real-life HTML <ruby> tag example in HTML that uses Japanese characters. To show the term meaning “Tokyo” (東京) with its pronunciation (とうきょう), the code would look like this:

The Code:

HTML

<p>Welcome to
<<ruby>>
東京 <rp>(</rp><rt>とうきょう</rt><rp>)</rp>
</<ruby>>
</p>

How it renders:

In a modern browser, you will see “とうきょう” sitting neatly above “東京”. If someone views this on a very old browser, they will see “東京 (とうきょう)” instead. This ensures your content is never “broken,” regardless of the user’s software.

HTML <ruby> Tag Usage

The primary usage is for phonetic guides, but it has several applications in modern web development:

Language Learning Tools: Helping students learn how to read Kanji, Hanzi, or Hanja by providing Pinyin or Furigana.
Scientific Notation: Occasionally used to provide small side notes for specific technical terms.
Digital Publishing: Essential for online newspapers, books, and comics in Asian markets.
Accessibility: It helps screen readers understand the relationship between the base text and the pronunciation guide.

By using the <ruby> tag annotation correctly, you maintain the semantic integrity of your document. This means search engines and assistive technologies can distinguish between the primary content and the supplementary guide.

HTML <ruby> Tag with rt and rp

Understanding the <ruby> tag with rt and rp is the difference between an amateur and a professional implementation.

rt Tag

The rt tag is where you place your metadata. You should keep this text short. If the annotation is longer than the base text, the browser will automatically add spacing to the base text to ensure the layout remains balanced.

rp Tag

While most modern browsers (Chrome, Edge, Firefox, Safari) support <ruby> characters, some legacy systems or niche text-only browsers might not. The rp tag acts as a safety net. It contains characters—usually opening and closing parentheses—that should only be displayed if the browser doesn’t know how to render the rt tag properly.

HTML <ruby> Tag Attributes

The <ruby> tag primarily supports the Global Attributes and Event Attributes in HTML5.

class/id: Used for styling the <ruby> group with CSS.
style: Used for inline CSS modifications.
title: Can provide extra information when a user hovers over the text.
lang: This is particularly useful. You can set the language of the <ruby> base (e.g., lang=”ja”) to help search engines index the content correctly.

While there are no unique “<ruby>-only” attributes like “src” or “href”, the power of the tag comes from how it interacts with CSS properties like <ruby>-position” and “<ruby>-align”.

HTML <ruby> Tag Elements Comparison

To help you remember how these elements work together, here is a quick reference table:

Tag	Name	Purpose	Requirement
<ruby>	<ruby> Annotation	The main container for the text and guide.	Mandatory
rt	<ruby> Text	Contains the pronunciation or explanation.	Mandatory
rp	<ruby> Parentheses	Provides fallback brackets for old browsers.	Optional

<ruby> Tag Browser Support

Chrome, Firefox, Safari, and Edge are all current browsers that support it. But older or antiquated browsers might not fully support <ruby> annotations. In these situations, the <rp> tag makes sure that the content is still readable by showing fallback parentheses.

How to Create a <ruby> Tag in HTML

If you are adding this to your project for the first time, follow these steps to ensure a clean result:

Find the Base: Pick the term that requires help.
Take the lid off: Put a <ruby> tag around the word.
Add a backup: Put an opening parenthesis next to an RP tag.
Define the Guide: Use the rt tag to write the pronunciation.
Close Fallback: Place another rp tag with a closing parenthesis.
Close the Container: End with the closing <ruby> tag.

This method ensures that your <ruby> tag in HTML is robust and professional.

Best Practices for Using the HTML <ruby> Tag

Keep it short: The annotation should be much smaller and shorter than the underlying text so that it looks balanced.
Don’t use archaic HTML tags: to adjust the font size of the rt tag. Use CSS instead. You can change the colour or size of the <ruby> text with CSS.
Mobile Test: Make sure that the extra height of the <ruby> text doesn’t cause lines to overlap in your mobile view.
Language Tags: Always use the lang attribute if the <ruby> text is in a different language than the surrounding content.

The <ruby> tag is a specialised yet vital tool for global web development. It allows for the elegant display of pronunciation guides and annotations, ensuring that complex characters are accessible to all readers.

By learning the <ruby> tag syntax in HTML and properly utilising the rt and rp tags, you can create linguistically accurate and visually appealing websites.

Whether you are building for a global audience or a specific niche, the <ruby> tag usage ensures your typography remains clean, functional, and user-friendly.

FAQs

Which browsers support the ruby tag?

Google Chrome, Mozilla Firefox, Apple Safari, and Microsoft Edge are all current browsers that fully support the ruby tag. The rp tag gives older browsers a readable backup.

Can I use the ruby tag for English text?

Yes, the ruby tag is mostly for East Asian languages, but you can use it for any language if you need to add a brief note above a word, as for acronyms or technical terms.

Is the rp tag mandatory inside a ruby tag?

No, the rp tag is optional. However, using it is a best practice for "graceful degradation," ensuring that users on outdated browsers can still understand the context of the HTML ruby tag annotation.

How do I change the colour of the pronunciation guide?

You can use CSS to style the rt element directly. For instance, rt {colour: red; } will change the colour of the text in the annotation but not the underlying text.

Can I have multiple rt tags in one ruby tag?

Yes, the ruby tag syntax lets you make complicated structures where more than one rt tag points to distinct areas of the underlying text. However, a simple one-to-one mapping is the most usual.