Bopomofo Ruby Text (React ruby typography component)

Semantic <ruby> / <rt> / <rp> markup annotates Chinese characters with Bopomofo (Zhuyin) symbols (tone marks are simplified to the right-hand side, following the horizontal-writing convention) or Hanyu Pinyin. Switching modes fades the annotations in character by character, and hovering a character highlights and slightly enlarges it together with its annotation — suited to language teaching, children's books, and literacy interfaces.

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<ZhuyinRubyText/>

    </div>
  );
}

Installation

npx webberui@latest add https://webberui.com/r/zhuyin-ruby-text.en.json

Usage

import { ZhuyinRubyText } from "@/components/ui/zhuyin-ruby-text";

<ZhuyinRubyText
  items={[
    { char: "Phonetic", zhuyin: "ㄓㄨˋ", pinyin: "zhù" },
    { char: "sound", zhuyin: "ㄧㄣ", pinyin: "yīn" },
    { char: "! " },
  ]}
  mode="zhuyin"
  size="md"
/>

The component also exports zhuyinRubySampleLines (sample data for the first two lines of the children's song 〈SmallStars〉, about 30 characters) so you can preview it quickly. That is only a small demo dataset — in practice, produce an items array of the same shape from your edited content or from a Bopomofo / Pinyin conversion service. Punctuation simply omits zhuyin and pinyin, and is then rendered as plain text and excluded from the hover highlighting.

Props

Accessibility

• It uses semantic <ruby> / <rt> / <rp> markup, so environments without ruby typography support fall back to showing the annotations in parentheses
• Annotation content is hidden from screen readers (aria-hidden), so Bopomofo symbols and tone marks are not read out one by one and do not disrupt the meaning
• When the user has "reduce motion" enabled at the system level, a mode switch plays no fade in and hover does not scale (only the color change remains)
• The outermost container is marked lang="zh-TW", helping assistive technology pick the right voice