Skip to content
kanji.js

Usage

kanji.js exports one class, Kanji, and every method on it is static. Import it and call the methods directly. You never need to create an instance.

Importing#

The package is a UMD build, so the import depends on your environment.

ES modules (bundlers, TypeScript, Node.js)
import Kanji from 'kanji.js'
CommonJS (Node.js)
const Kanji = require('kanji.js')
Browser script tag
<script src="https://cdn.jsdelivr.net/npm/kanji.js@1.6.2/dist/kanji.min.js"></script>
<!-- the global `Kanji` is now available -->

Look up a character#

getDetails() finds a single character and returns everything the dictionary has on it. It returns null if the character isn't in the dictionary, so check the result before you use it.

const ki = Kanji.getDetails('気')
// {
//   literal: '気',
//   meanings: ['spirit', 'mind', 'air', 'atmosphere', 'mood'],
//   onyomi: ['キ', 'ケ'],
//   kunyomi: ['いき'],
//   stroke_count: 6,
//   grade: 1,
//   jlpt: 4,
//   freq: 113
// }


Kanji.getDetails('a')  // null

The Character data page explains what each field means.

search() scans the whole dictionary and returns an array of characters. There are two kinds of options:

  • Filters (grade, jlpt) remove characters that don't match.
  • Ranking hints (meaning, romaji) move the best matches to the top. They never remove anything.
// Only first-grade characters, best match for "counter for days" first
Kanji.search({ grade: 1, meaning: 'counter for days' })[0].literal  // '日'


// JLPT levels 1 and 2 (old four-level scale)
Kanji.search({ jlpt: { min: 1, max: 2 } }).length  // 1946


// Characters read "mizu", best match first
Kanji.search({ romaji: 'mizu' })[0].literal  // '水'

Random character#

Kanji.random()
// e.g. { literal: '幬', meanings: ['cover up', 'curtain'], grade: null, jlpt: null, … }

random() picks from the whole dictionary. Most entries are rare characters with no grade or JLPT level. To pick from common characters only, see Pick a random character from one level.

The whole dictionary#

dump() returns the full array of 13,108 entries. Use it with your own filter, find or map when search() doesn't do what you need.

const all = Kanji.dump()
const simple = all.filter(k => k.stroke_count <= 3)

Next steps#