Normalize Persian Text

Text pasted from Arabic keyboards and legacy fonts is full of look-alike codepoints — ي instead of ی، ك instead of ک — that break search, duplicate database rows, and render inconsistently. This utility unifies them onto their canonical Persian letters in one pass, with opt-in cleanup for digits, diacritics, half-spaces, and whitespace. Price Input uses its digit helper internally.

Last updated October 20, 2018

Overview

Edit the sample or flip the toggles; the normalized output updates as you type.

Installation

$ npx shadcn@latest add @persianlabsui/normalize-persian-text

Usage

import { normalizePersianText } from "@/lib/normalize-persian-text"
 
// Letters are always unified:
normalizePersianText("كتاب ي") // کتاب ی
 
// Opt-ins for lossier pipelines:
normalizePersianText("۱۲۳", { digits: true }) // 123
normalizePersianText("مُستَحِقّ", { diacritics: true }) // مستحق
normalizePersianText("خانه ‌ها", {}) // خانه ها — stray ZWNJ dropped
 
// Aggressive search-key builder:
normalizePersianText("كتاب‌‌هاي خـواندني؟", { digits: true, diacritics: true })

Examples

Search keys

Turn every lossy option on to build a stable key from messy input — Arabic codepage letters, vocalized text, broken half-spaces, Persian digits:

Behavior

Letter unification (always on) — ي ى → ی, ك → ک, أ إ ٱ → ا, ة → ه. Everything else passes through untouched.
Digits — off by default; { digits: true } folds ۰-۹ and ٠-٩ to ASCII via Normalize Persian Digits.
Diacritics — off by default; { diacritics: true } strips harakat, Quranic superscripts, and kashida elongations (کتاـــب → «کتاب»).
Half-space repair — on by default; consecutive ZWNJs collapse to one and strays beside spaces, punctuation, or string edges are dropped. Meaningful half-spaces like «خانه‌ها» survive. Disable with { zwnj: false }.
Spaces — on by default; blank runs collapse to a single space and ends are trimmed. Line breaks survive. Disable with { spaces: false }.

API Reference

normalize-persian-text

Prop	Type	Default	Description
normalizePersianText(value, options?)	(value: string, options?: NormalizePersianTextOptions) => string	—	Normalizes Persian text for storage, comparison, and display. Arabic codepage look-alikes are always unified onto their canonical Persian letters (ي→ی, ك→ک, ة→ه, أ/إ/ٱ→ا); every other behavior is opt-in via options.
options.digits	boolean \| undefined	—	Folds Persian (۰-۹) and Arabic-Indic (٠-٩) digits to plain 0-9 through the normalize-persian-digits helper. Defaults to false.
options.diacritics	boolean \| undefined	—	Strips Arabic diacritics (harakat), Quranic superscripts, and kashida elongations. Letters such as ش or قّ keep their base glyph. Defaults to false.
options.zwnj	boolean \| undefined	—	Repairs broken half-spaces: consecutive ZWNJs collapse to one, and stray ones sitting next to spaces, punctuation, or the string edges are dropped. Meaningful half-spaces like «خانه‌ها» survive. Defaults to true.
options.spaces	boolean \| undefined	—	Collapses runs of blanks (spaces, tabs, non-breaking spaces) to a single space and trims both ends. Line breaks are preserved. Defaults to true.

Edit this page on GitHub

PreviousNormalize Persian Digits NextNumber to Persian Words