CJK Word Count Textarea

A Chinese "word count" is not the same thing as an English one: every Han character counts as one, while an English run of letters counts as one word as a whole — and databases or legacy systems often count bytes instead. This textarea puts all three counting modes into a segmented switch at the bottom right and shows "current / limit" live next to an SVG progress ring that turns amber past the warnAt ratio and red, with a quick shake, once the limit is exceeded. While an IME (Zhuyin, kana and so on) is composing, the count is frozen so composition letters are never counted; with hardLimit on, input past the limit is blocked, but trimming waits until composition ends so a character being composed is never cut in half. Both the text value and the counting mode support controlled and uncontrolled modes.

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">

<CjkWordCountTextarea/>

    </div>
  );
}

Installation

npx webberui@latest add https://webberui.com/r/cjk-word-count-textarea.en.json

Usage

import { CjkWordCountTextarea } from "@/components/ui/cjk-word-count-textarea";

<CjkWordCountTextarea
  label="Post content"
  maxCount={140}
  defaultMode="words"
  autoResize
  onChange={(text, counts) => {
    // counts carries the numbers for all three modes
    console.log(counts.words, counts.chars, counts.bytes);
  }}
/>

Props

CjkCounts

CountCjkOptions

CjkWordCountLabels

countCjk(text, mode, opts) and clampCjk(text, max, mode, opts) are also named exports, so form validation or server code can count and trim with exactly the same rules; both are pure functions with no browser API dependency.

How it works

• Words mode: each Han character (plus Japanese kana and Korean Hangul) counts as one; runs of Latin letters, digits and the like are split on whitespace or CJK characters and count as one word each; full-width punctuation is not counted by default, or counted one by one with countPunctuation: true. For example, "我買了 3 本 React 書" counts as 7.
• Chars mode counts Unicode code points (Array.from), so surrogate pairs such as emoji are never split in two.
• Bytes mode defaults to UTF-8 length (most Han characters are 3 bytes); many legacy systems in Taiwan count in Big5 (2 bytes per Han character), which you can match with countOptions={{ bytesPerCjk: 2 }}.
• The hard limit uses binary search to find the longest valid prefix: the count only grows as the prefix grows, so there is no need to recount character by character.
• autoResize resets the height before reading scrollHeight, so the field shrinks back when content is removed.

Accessibility

• The label is associated with the textarea via htmlFor; without a label, the placeholder becomes the aria-label
• The count text is linked to the textarea via aria-describedby; aria-invalid is set when over the limit
• The mode switch is a role="radiogroup" whose tabs are role="radio" with aria-checked, using a roving tabindex; arrow keys cycle through modes, with a focus-visible ring
• Warnings live in a role="status", aria-live="polite" region and are announced only once, at the moment warnAt or the limit is crossed, rather than on every keystroke; the progress ring and warning icon are hidden from assistive technology
• When the user has reduce motion enabled at the system level, the over-limit shake and the sliding mode pill animation are disabled and the state switches directly