hangul.dev

Documentation

Text Processing

Decompose and compose Hangeul syllables programmatically. Break any syllable into its constituent jamo (consonants and vowels).

import { decompose } from 'hangul.dev';

const jamo = decompose('한글');
// ['ㅎ','ㅏ','ㄴ','ㄱ','ㅡ','ㄹ']

Unicode Normalization

Convert between NFC and NFD forms for Hangeul text. Essential for cross-platform compatibility and text search.

import { normalize } from 'hangul.dev';

// NFC: precomposed syllables
normalize('한글', 'NFC');
// NFD: decomposed jamo sequences
normalize('한글', 'NFD');

Input Method Engine

Build custom Hangeul input methods with our compositing engine. Handles real-time jamo composition with proper backspace behavior.

import { IME } from 'hangul.dev';

const ime = new IME();
ime.input('ㅎ'); // ㅎ
ime.input('ㅏ'); // 하
ime.input('ㄴ'); // 한

Romanization

Convert Hangeul to Revised Romanization or McCune-Reischauer. Supports custom rule sets for names and addresses.

import { romanize } from 'hangul.dev';

romanize('서울특별시');
// "Seoul-teukbyeolsi"

romanize('김치', { system: 'MR' });
// "kimch'i"

Syllable Validation

Check if a given character is a valid Hangeul syllable, jamo, or compatibility jamo. Identify character types instantly.

import { isHangul } from 'hangul.dev';

isHangul('가'); // true
isHangul('ㄱ'); // true (jamo)
isHangul('A');  // false

Search & Matching

Implement Korean-aware search with initial consonant matching (초성 검색). Match "ㅎㄱ" against "한글" for fast autocomplete.

import { search } from 'hangul.dev';

const data = ['한글', '한국', '항공'];
search(data, 'ㅎㄱ');
// ['한글', '한국', '항공']

search(data, 'ㅎㄱㄹ');
// ['한글']

Rendering Engine

Render Hangeul with proper vertical metrics and glyph shaping. Supports variable font weight and custom stroke styles.

Jamo Algebra

Perform algebraic operations on jamo: combine initial + medial + final, extract components, test compatibility, and transform between jamo types.

import { Jamo } from 'hangul.dev';

Jamo.combine('ㅎ','ㅏ','ㄴ');
// '한'

Jamo.initial('한'); // 'ㅎ'
Jamo.medial('한');  // 'ㅏ'
Jamo.final('한');   // 'ㄴ'

Getting Started

Install hangul.dev in your project and start building Hangeul-aware applications in minutes.

npm install hangul.dev

# or
yarn add hangul.dev

# or
pnpm add hangul.dev

Understanding Hangeul

Hangeul (한글) is the writing system for the Korean language, created in 1443 by King Sejong the Great (세종대왕). Unlike scripts that evolved over millennia, Hangeul was deliberately designed with scientific principles in mind.

The Three Principles

The vowel system is built on three fundamental strokes representing cosmological concepts:

ㅣ (i) represents Heaven - the vertical stroke
ㅡ (eu) represents Earth - the horizontal stroke
ㅏ (a) represents Human - the mediation between heaven and earth

Syllable Block Structure

Korean syllables are composed in blocks, each containing two to four jamo (자모). A syllable block follows the pattern:

Initial (초성) + Medial (중성) [+ Final (종성)]

Example: 한 = ㅎ (initial) + ㅏ (medial) + ㄴ (final)
         가 = ㄱ (initial) + ㅏ (medial)

Unicode Ranges

Hangeul is encoded across several Unicode blocks:

Hangeul Syllables:       U+AC00 - U+D7A3  (11,172 characters)
Hangeul Jamo:            U+1100 - U+11FF  (256 characters)
Hangeul Compatibility:   U+3130 - U+318F  (96 characters)
Hangeul Jamo Extended-A: U+A960 - U+A97F  (32 characters)
Hangeul Jamo Extended-B: U+D7B0 - U+D7FF  (80 characters)

Algorithmic Decomposition

The position of a Hangeul syllable in Unicode is algorithmically determined. Given the codepoint of a syllable, you can compute its constituent jamo:

const SYLLABLE_BASE = 0xAC00;
const INITIAL_COUNT = 19;
const MEDIAL_COUNT = 21;
const FINAL_COUNT = 28;

function decompose(syllable) {
    const code = syllable.charCodeAt(0) - SYLLABLE_BASE;
    const initial = Math.floor(code / (MEDIAL_COUNT * FINAL_COUNT));
    const medial = Math.floor((code % (MEDIAL_COUNT * FINAL_COUNT)) / FINAL_COUNT);
    const final_ = code % FINAL_COUNT;
    return { initial, medial, final: final_ || null };
}

Building with hangul.dev

This library provides high-level abstractions over these Unicode operations, making it simple to build applications that correctly handle Korean text. Whether you're building a search engine, text editor, or internationalization pipeline, hangul.dev handles the complexity.