HTML <ruby> Tag: Usage, Attributes, and Real-World Examples

By Cristian G. Guasch •  Updated: 09/25/23 •  9 min read

In today’s digital age, mastering the art of HTML is a must for anyone looking to make their mark online. An essential part of this coding language that I’ll be diving into today is the HTML <ruby> tag – a lesser-known, but incredibly useful tool in web development.

The <ruby> tag allows us to insert ruby annotations into our website text – these are small texts placed above or below characters, primarily used in East Asian typography. Think of it as a way to provide pronunciation or clarification for specific characters. But don’t worry if it all seems a bit complex now – by the end of this article, you’ll understand the ins and outs of using this versatile tool.

So how exactly does one use the HTML <ruby> tag? What attributes can we manipulate within it? And what are some real-world examples we can learn from? Stay with me – I’m about to break it down.
Diving headfirst into the world of HTML, there’s one element that often goes unnoticed: the <ruby> tag. This little gem is used to provide pronunciation guidance for East Asian typography – which can be a real game-changer when it comes to creating accessible web content.

The <ruby> tag, in essence, creates what’s known as a ruby annotation. That’s a small run of text that sits above or next to base text, usually used with East Asian scripts like Japanese or Chinese. Here’s an example:

  漢 <rt> Kan </rt>
  字 <rt> Ji </rt>

In this snippet, ‘Kan’ and ‘Ji’ are the ruby texts providing pronunciation aids for the base texts ‘漢’ and ‘字’. The HTML renderer places these annotations above the base text in vertical writing mode or right after the base text in horizontal writing modes.

Now you might be thinking, “What if I need more than just one annotation?” Well, that’s where our friends <rbc> and <rtc> come into play! These tags allow you to group your base characters (<rbc>) and their corresponding ruby texts (<rtc>) together. It might look something like this:

  <rbc> 日本語 </rbc>
  <rtc> Nihongo </rtc>

While using these tags is fairly straightforward, it’s important not to confuse them with similar tags such as <rb> (for single base character) and <rp> (provides parentheses for browsers not supporting ruby annotations). Remembering their distinct uses will save you from some common pitfalls.

Indeed understanding the intricacies of HTML elements like the <ruby> tag takes time but it’s worth every second spent! With practice comes perfection so don’t be afraid to explore and experiment with these tags on your own. After all, the best way to learn is by doing. And who knows? You might just stumble upon a new, innovative way to use these versatile tools!

Attributes of the HTML <ruby> Tag

When it comes to HTML, it’s all about understanding the ins and outs of tags. One such tag that’s often overlooked but incredibly useful is the <ruby> tag. This handy little element gives us a way to represent small annotations used in East Asian typography known as ruby annotations.

Let’s dive into some of its key attributes:

Here’s an example to help illustrate how these attributes work together:


In this case, we’re using the <rb> tag to define our base text (in Japanese), then applying <rt> as our annotation (the English translation). With these three attributes, you can create clear and informative ruby annotations on your site.

However, there are common mistakes people make while using these tags. One frequent error is forgetting to close off each individual tag properly. In HTML, every opening tag needs a corresponding closing one – so don’t forget those / characters!

Another typical mistake is confusing the use of rb and rt. Remember: rb sets up what you’re annotating, while rt provides the actual annotation.

By getting a handle on these attributes and avoiding common pitfalls, you’ll be well on your way to mastering HTML’s <ruby> tag!

Practical Examples Using HTML <ruby>

Diving into practical examples, let’s explore how the HTML <ruby> tag can be utilized. For those who may not know, the <ruby> tag is primarily used to offer pronunciation assistance for certain East Asian characters. It’s a handy tool that certainly makes life easier for web designers and developers working on multilingual sites.

Consider this basic example:


Here, “漢字” represents the base character while “Kanji” is its phonetic equivalent. The <rt> tag within the <ruby> element specifies the ruby text component of a ruby annotation.

Now, let’s add a little complexity to our example:

  漢 <rp>(</rp><rt>Kan</rt><rp>)</rp> 字 <rp>(</rp><rt>Ji</rt><rp>)</rp>

In this instance, we’re using the optional <rp> (Ruby Parentheses) tags to provide visual cues for browsers that don’t support the main <ruby> tag. If your browser doesn’t recognize or support this tag, it’ll display parentheses around the phonetic text.

However, it’s important to be aware of common mistakes when using these tags. A frequent error is forgetting to include both opening and closing tags for each element (<ruby>,<rt>, and optionally,< rp>). Also remember that even though most browsers ignore any CSS styling applied directly to these elements, you can still style them indirectly by applying CSS rules to their parent elements.

While there are more complex uses of these tags involving double-sided ruby annotations or multi-ruby blocks with shared bases – these simple examples should serve as an ideal starting point!

Common Mistakes with the HTML <ruby> Tag

I’m here to shed some light on a few common mistakes that people tend to make when using the HTML <ruby> tag. This is not about shaming or pointing fingers, but rather creating awareness so you can become better in your coding process.

One of the most significant blunders I’ve seen is ignoring browser compatibility. It’s important to know that not all browsers support the <ruby> tag. As of now, Internet Explorer and Edge do not fully support it. So, if you’re coding for a site that gets significant traffic from these browsers, you might want to rethink using this particular tag.

  漢 <rt> kan </rt>
  字 <rt> ji </rt>

Another frequent mistake involves misusing or neglecting <rp> and <rt> tags within a <ruby> element. The <rp> (Ruby Parentheses) tag should be used to show parentheses around the ruby text component in browsers that don’t support ruby annotations. On the other hand, <rt> (Ruby Text) serves as a container for explanatory text/pronunciation guide in East Asian typography.

  Base text <rp>(</rp><rt>Ruby Text</rt><rp>)</rp>

Incorrect nesting of these tags can lead to undesired results or even break your layout on certain browsers.

Finally, another glitch I often spot is using multiple base texts for one annotation or vice versa – which goes against proper usage norms.

<!-- Incorrect Usage -->
  Base1 Base2 <rt>Ruby Text</rt>

<!-- Correct Usage -->
  Base <rt>Ruby Text1</rt><rt>Ruby Text2</rt>

In conclusion, let’s remember that while the <ruby> tag can be quite handy for specific use-cases, it requires careful implementation. Avoiding these common errors will ensure a smoother experience for you and your end-users.

Conclusion: Enhancing Web Typography with <ruby>

I’ve spent some time now discussing the HTML <ruby> tag, its usage, attributes and examples. It’s clear that this small yet mighty tag is a significant tool in enhancing web typography.

The <ruby> tag plays an important role in providing phonetic and pronunciation guides for certain languages such as Japanese Kanji or Chinese Hanzi. It allows us to add ruby text (small annotations) above or below normal text, making it easier for readers to understand unfamiliar characters or symbols.

Here’s a simple example of how it works:

  漢 <rt> kan </rt>
  字 <rt> ji </rt>

This code will display ‘kan’ above ‘漢’ and ‘ji’ above ‘字’.

Still, I see many developers shy away from using the <ruby> tag due to lack of knowledge or fear of making mistakes. Common errors include forgetting to encapsulate ruby text within the <rt> tags, not using the correct syntax, and misunderstanding when its usage is appropriate.

But with practice comes mastery. Here are few tips to avoid common pitfalls:

There’s no doubt that grasping all aspects of HTML can be quite a task – but don’t let that deter you! The beauty of coding lies in continuous learning and improvement. The more you explore different elements like the humble HTML <ruby>, the closer you get to creating more accessible and user-friendly websites!

Remember, every little bit helps when it comes down to enhancing web typography!

Cristian G. Guasch

Hey! I'm Cristian Gonzalez, I created HTML Easy to help you learn HTML easily and fast.

Related articles