Cnchar: A Lightweight JavaScript Library for Pinyin, Stroke Order & Idioms

Cnchar is a versatile Hanzi toolkit designed to handle pinyin, stroke order, radicals, idioms, and voice synthesis. It is built for high portability and runs in almost any JavaScript environment.

Key Advantages

• Cross-Platform Compatibility – Works seamlessly in browsers, Node.js, mini-programs, games, React Native, Weex, Uniapp, Electron, and Webpack.
• Native TypeScript Support – The core library and all official plugins are built with TypeScript for robust development.
• Comprehensive Feature Set – Provides extensive support for pinyin, strokes, idioms, speech, and more.
• Modular Plugin Architecture – Features are split into individual plugins, allowing you to load only the specific functionality your project requires.
• Offline Capabilities – Several dictionaries function entirely offline, and you have the option to host them on your own infrastructure.
• Lightweight Footprint – The minified version is only 75kb, while the zipped version (which includes a substantial pinyin dictionary) is just 50kb.

Installation

Installing via npm

To get started, install the core library:

npm i cnchar

You can then add optional plugins based on your needs:

npm i cnchar-poly cnchar-order cnchar-trad cnchar-draw cnchar-idiom cnchar-xhy cnchar-radical cnchar-words cnchar-explain cnchar-voice cnchar-random cnchar-code cnchar-input cnchar-info cnchar-name

Alternatively, install the entire suite at once:

npm i cnchar-all

Using a CDN

To include the core library:

<script src="https://fastly.jsdelivr.net/npm/cnchar/cnchar.min.js"></script>

To add specific plugins:

<script src="https://fastly.jsdelivr.net/npm/cnchar-poly/cnchar.poly.min.js"></script>
<script src="https://fastly.jsdelivr.net/npm/cnchar-order/cnchar.order.min.js"></script>

Or use the all-in-one package:

<script src="https://fastly.jsdelivr.net/npm/cnchar-all/cnchar.all.min.js"></script>

Implementation

Modern Environments (Webpack/Vite)

import cnchar from 'cnchar';
import 'cnchar-poly'; // Import additional plugins as required

console.log('汉字'.spell()); // Using the prototype method
console.log(cnchar.spell('汉字')); // Using the API call

Node.js

var cnchar = require('cnchar');
var poly = require('cnchar-poly');

cnchar.use(poly);

console.log('汉字'.spell());
console.log(cnchar.spell('汉字'));

Direct Browser Integration

<script src="https://fastly.jsdelivr.net/npm/cnchar/cnchar.min.js"></script>
<script src="https://fastly.jsdelivr.net/npm/cnchar-poly/cnchar.poly.min.js"></script>
<script>
console.log('汉字'.spell());
console.log(cnchar.spell('汉字'));
</script>

Core Capabilities

1. Pinyin Processing – Retrieve pinyin for Chinese characters with support for first-letter extraction, case sensitivity, array output, and polyphone (multi-pronunciation) detection. It also manages tone marks and multi-syllable words.

2. Stroke Data – Access stroke counts, stroke order, and official stroke names. When used in a browser, the library can visually render stroke-order animations.

3. Character Conversion & Lookup – Convert text between Simplified, Traditional, and "Martian" (stylized/leet-speak) Chinese. You can also search for characters by pinyin, stroke count, or specific stroke order.

4. Extended Features

   • Idiom searches (by character, pinyin, or stroke count)
   • Xiehouyu (allegorical sayings) database with fuzzy search support
   • Radical lookups
   • Random generation of pinyin, characters, words, and idioms
   • Detailed character info and encoding queries
   • Built-in support for Pinyin and Wubi input methods
   • Support for custom user-defined plugins and data sets
   • Automated Chinese name generation