@mapbox/mapbox-gl-rtl-text

@mapbox/mapbox-gl-rtl-text adds right-to-left text rendering to Mapbox GL JS. It is an Emscripten (WebAssembly) port of the subset of International Components for Unicode (ICU) functionality needed to shape and reorder Arabic and Hebrew text so it displays correctly on maps.

The package exposes Arabic shaping and Unicode Bidirectional Algorithm functions and is designed to be loaded by Mapbox GL JS as an RTL text plugin. It ensures place names and labels in right-to-left scripts appear in the correct visual order and with the appropriate contextual glyph forms.

What You Get

• applyArabicShaping to convert Arabic characters to their correct presentation forms
• processBidirectionalText implementing the Unicode Bidirectional Algorithm over logical-order input
• A prebuilt WebAssembly (ICU) module loadable directly by Mapbox GL JS
• Support for Arabic and Hebrew right-to-left rendering on maps

Common Use Cases

• Enabling correct rendering of Arabic and Hebrew labels in Mapbox GL JS maps
• Shaping and reordering RTL strings before layout in custom text pipelines
• Serving multilingual maps to right-to-left language audiences

Under The Hood

Architecture

The core is a compiled icu.wasm module produced by Emscripten from ICU’s bidi and shaping routines, wrapped by C shims (ubidi_wrapper.c, ushape_wrapper.c) and exposed to JavaScript through index.js. The public surface is two functions — applyArabicShaping for contextual glyph selection and processBidirectionalText for the bidirectional reordering — that GL JS calls internally once the plugin is registered.

Tech Stack

C/ICU compiled to WebAssembly via Emscripten (see build_icu.sh), with a thin JavaScript loader bundled by Rollup. Distributed as a single script intended to be loaded by Mapbox GL JS.

Code Quality

The project is narrowly scoped and stable, with ESLint configuration, CI, and CODEOWNERS governance from Mapbox. Because it wraps battle-tested ICU code, correctness of the underlying algorithms comes from ICU itself; the repo’s own surface is small.

API Design

Most users never call the functions directly — they register the built script with mapboxgl.setRTLTextPlugin and GL JS handles the rest, which is a one-line integration. For advanced use, the two exported functions are clearly documented in terms of logical vs. visual character order, making direct use approachable for those building custom text layout.