icd-11-search

A fast, developer-friendly ICD-11 search engine for healthcare applications.

icd-11-search provides a simple, reliable way to search and retrieve all 13,062 ICD-11 codes using fuzzy matching and type-safe APIs — without requiring direct integration with the WHO ICD API.

Why This Library Exists

Integrating ICD-11 into healthcare software is harder than it should be.

Developers face:

• Complex hierarchical data
• Slow or rate-limited external APIs
• Poor search experience for clinicians
• Inconsistent results when users misspell diagnoses

Clinicians, on the other hand, need:

• Fast diagnosis lookup
• Tolerance for spelling mistakes
• Clear, accurate results
• Minimal friction during patient care

This library exists to bridge that gap.

It improves developer experience with a zero-setup API, and improves clinical accuracy by making ICD-11 codes easy to find, even with imperfect input. Better search leads to better diagnosis capture, which supports reporting, monitoring, and public health decision-making.

What This Library Does

• Loads the complete ICD-11 MMS dataset (26 chapters, 13,062 codes)
• Builds an in-memory search index using Fuse.js
• Exposes simple, predictable APIs for:
  • Fuzzy search
  • Code-based lookup
  • Chapter-based retrieval
• Works offline, without external API calls

Key Features

| Feature | Description | |---------|-------------| | 🔍 Fuzzy Search | Typo-tolerant diagnosis search (e.g. diabtes → diabetes) | | 📦 Complete Dataset | All 26 chapters, 13,062 codes | | 🔒 TypeScript-First | Full type safety with exported interfaces | | ⚡ Zero Configuration | Install and use immediately | | 🌐 Runtime Agnostic | Works in Node.js, Bun, and modern bundlers |

Installation

npm install icd-11-search

yarn add icd-11-search

bun add icd-11-search

Quick Start

import { search, getByCode, getChapters } from 'icd-11-search';

// Fuzzy search (returns up to 8 results by default)
const results = search('diabetes');
console.log(results[0].item.title);
// → "Type 2 diabetes mellitus"

// Exact lookup
const code = getByCode('2A00');
console.log(code?.title);
// → "Primary neoplasms of brain"

// List chapters
console.log(getChapters().length);
// → 26

API Reference

Real-Time Autocomplete

autocomplete(query: string, limit?: number): ICD11Code[]

Best for real-time search as user types. Optimized for partial words (e.g., "dia" → "diabetes", "fea" → "fear"). Returns 8 results by default.

// As user types "dia"
const results = autocomplete('dia');
// → [{ code: '5A12', title: 'Malnutrition-related diabetes mellitus', ... }]

// As user types "fea"
const results = autocomplete('fea');
// → Results containing "fear", "febrile", etc.

// Get more results
const results = autocomplete('heart', 20);

Fuzzy Search

search(query: string, options?: SearchOptions): SearchResult[]

Searches ICD-11 titles and codes using fuzzy matching. Returns 8 results by default.

// Basic search
const results = search('diabetes');

// Get more results
const results = search('diabetes', { limit: 20 });

// With filtering
const results = search('diabetes', {
  threshold: 0.3,           // Stricter matching (0 = exact, 1 = loose)
  chapter: 'Endocrine, nutritional or metabolic diseases',
  kind: 'stem',             // Only stem codes (no extensions)
  limit: 10,
  includeMatches: true      // For highlighting
});

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | limit | number | 8 | Maximum results to return | | threshold | number | 0.4 | Fuzzy threshold: 0.0 (exact) to 1.0 (loose) | | keys | ('title' \| 'code')[] | ['title', 'code'] | Fields to search | | chapter | string | — | Filter by chapter name | | kind | 'stem' \| 'extension' | — | Filter by code type | | includeMatches | boolean | false | Include match indices for highlighting |

Code-Based Search

searchByCode(code: string, limit?: number): ICD11Code[]

Returns codes starting with the given prefix.

const results = searchByCode('2A');
// All codes starting with "2A"

Title-Only Search

searchByTitle(title: string, options?: SearchOptions): SearchResult[]

Fuzzy search on titles only.

const results = searchByTitle('heart failure');

Chapter-Based Retrieval

getByChapter(chapter: string, limit?: number): ICD11Code[]

Get codes from a specific chapter.

const results = getByChapter('Neoplasms', 50);

All Codes

getAllCodes(limit?: number): ICD11Code[]

Get all codes with optional limit.

const codes = getAllCodes(100);

Direct Lookup

These methods return a single result (no limit).

Exact Code Match

const code = getByCode('2A00');
// → { code: '2A00', title: 'Primary neoplasms of brain', ... }

Entity ID Lookup

const code = getByEntityId('1630407678');
// → { code: '02', title: 'Neoplasms', ... }

List All Chapters

const chapters = getChapters();
// → [{ name: 'Neoplasms', codeCount: 833 }, ...]

Total Code Count

const total = getTotalCount();
// → 13062

TypeScript Types

All types are exported:

import type {
  ICD11Code,
  SearchOptions,
  SearchResult,
  ChapterInfo,
  FuseMatch
} from 'icd-11-search';

ICD11Code

interface ICD11Code {
  entityId: string;   // WHO entity ID
  code: string;       // ICD-11 code (e.g., "2A00")
  title: string;      // Human-readable title
  kind: 'stem' | 'extension' | 'non-codable';
  classKind?: 'chapter' | 'block' | 'window' | 'category';
  chapter: string;    // Parent chapter name
}

SearchResult

interface SearchResult {
  item: ICD11Code;
  score: number;         // 0 = perfect match, 1 = worst
  matches?: FuseMatch[]; // For highlighting
}

Example: Diagnosis Autocomplete

import { search } from 'icd-11-search';

function autocomplete(query: string) {
  if (query.length < 2) return [];
  
  return search(query, { limit: 10 }).map(r => ({
    code: r.item.code,
    title: r.item.title,
    chapter: r.item.chapter
  }));
}

// Usage
const suggestions = autocomplete('diab');
// → [{ code: '5A12', title: 'Malnutrition-related diabetes mellitus', ... }, ...]

ICD-11 Chapters

This module includes all 26 ICD-11 chapters:

| Chapter | Codes | |---------|-------| | Certain infectious or parasitic diseases | 703 | | Neoplasms | 833 | | Diseases of the blood or blood-forming organs | 177 | | Diseases of the immune system | 172 | | Endocrine, nutritional or metabolic diseases | 425 | | Mental, behavioural or neurodevelopmental disorders | 659 | | Sleep-wake disorders | 59 | | Diseases of the nervous system | 563 | | Diseases of the visual system | 487 | | Diseases of the ear or mastoid process | 104 | | Diseases of the circulatory system | 397 | | Diseases of the respiratory system | 246 | | Diseases of the digestive system | 668 | | Diseases of the skin | 538 | | Diseases of the musculoskeletal system or connective tissue | 303 | | Diseases of the genitourinary system | 392 | | Conditions related to sexual health | 48 | | Pregnancy, childbirth or the puerperium | 400 | | Certain conditions originating in the perinatal period | 447 | | Developmental anomalies | 892 | | Symptoms, signs or clinical findings, not elsewhere classified | 940 | | Injury, poisoning or certain other consequences of external causes | 1395 | | External causes of morbidity or mortality | 691 | | Factors influencing health status or contact with health services | 625 | | Codes for special purposes | 21 | | Supplementary Chapter Traditional Medicine Conditions | 877 |

How It Works

1. Preprocessed Dataset: All ICD-11 codes are bundled at build time
2. Fuse.js Index: Lazy-initialized fuzzy search index
3. In-Memory: No network calls, predictable performance

Data Source

ICD-11 MMS dataset sourced from the WHO ICD API (2025-01 release).

Who Should Use This

• Developers building EMRs / HMIS
• Health-tech startups
• Clinical decision support tools
• Reporting and surveillance systems
• Public health analytics platforms

License

MIT © 2026

Contributing

Contributions are welcome. Open an issue or submit a pull request.