Bopomofo Ruby Text (React ruby typography component)
A React ruby typography component that annotates Chinese characters with Bopomofo (Zhuyin) or Hanyu Pinyin above them — switch between Bopomofo and Pinyin, highlight a character on hover, adjust the annotation size and spacing. Suited to teaching materials, dictionaries, and children's sites.
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.
npx shadcn@latest add https://webberui.com/r/zhuyin-ruby-text.jsonPlayground
Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.
<ZhuyinRubyText />
Installation
npx shadcn@latest add https://webberui.com/r/zhuyin-ruby-text.jsonOr, once registries are configured in components.json, install it as @webberui/zhuyin-ruby-text.
Usage
import { ZhuyinRubyText } from "@/components/ui/zhuyin-ruby-text";
<ZhuyinRubyText
items={[
{ char: "注", zhuyin: "ㄓㄨˋ", pinyin: "zhù" },
{ char: "音", 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 〈小星星〉, 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
| Prop | Type | Default | Description |
|---|---|---|---|
items | ZhuyinRubyItem[] | — | Per-character annotation data; each entry is { char, zhuyin?, pinyin? } |
mode | "zhuyin" | "pinyin" | "none" | "zhuyin" | Annotation mode; none still reserves the annotation row's height, so switching does not shift the layout |
size | "sm" | "md" | "lg" | "md" | Type size (the characters and their annotations scale together) |
className | string | — | Forwarded to the outermost container |
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
Woodtype Flush Block
A woodtype flush heading — each line of a multi-line heading is solved onto the variable font's wdth axis so it stretches flush to both edges of the container, and on reveal the lines spring open from an extremely narrow width to the solved width, one after another.
CJK Number Roller
Numbers rolling between three forms — lowercase Chinese numerals, formal (financial) Chinese numerals, and Arabic digits — with automatic conversion to the formal amount form.