RTL Text

MapMetrics GL renders label text with a general-purpose text shaper. On its own, that shaper does not perform the glyph joining/reordering that Arabic, Hebrew, Persian and Urdu need. Without the RTL plugin, labels in those scripts render as disconnected, incorrectly-ordered characters — and the map does not throw an error. Nothing in the console tells you this is happening; the map just looks wrong for a subset of your users.

If your map (or your users' input) can contain Arabic, Hebrew, Persian or Urdu text, load the RTL plugin before you create the Map.

Loading the plugin

You must supply the plugin build yourself

MapMetrics does not currently host an RTL plugin bundle — there is no rtl-text asset on cdn.mapmetrics-atlas.net. The SDK ships the loader, not the plugin. Host a compatible RTL text plugin build on your own origin and point setRTLTextPlugin at it. The URL below is a placeholder; replace it with your own.

mapmetricsgl.setRTLTextPlugin(
  'https://your-own-host.example.com/rtl-text-plugin.js', // you must host this
  false // lazy
);

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
  center: [0, 0],
  zoom: 2,
});

setRTLTextPlugin(url, lazy):

• url — where to fetch the plugin script from. It's loaded from a worker via importScripts, so it must be reachable from your page (a plugin bundle hosted on a CDN, or one you serve yourself).
• lazy — if false (or omitted), the plugin is fetched and initialized immediately. If true, loading is deferred until the map actually encounters a tile that needs RTL shaping.

Call it once, before you create your first Map instance. Calling it a second time throws setRTLTextPlugin cannot be called multiple times.

Checking status

mapmetricsgl.getRTLTextPluginStatus();
// 'unavailable' | 'deferred' | 'requested' | 'loading' | 'loaded' | 'error'

The statuses:

Status	Meaning
unavailable	Not loaded, and setRTLTextPlugin hasn't been called.
deferred	URL is registered, but loading was deferred (lazy: true) and hasn't been triggered yet.
requested	A tile needed RTL shaping before the plugin was set.
loading	The worker is fetching/initializing the plugin.
loaded	Ready — RTL scripts will shape correctly.
error	The plugin failed to load (bad URL, network failure, etc.).

Why "lazy" exists

If most of your users never see RTL text, set lazy: true so the extra script isn't fetched on every page load — it's pulled in only the first time a tile actually needs it. If you know your map will regularly show Arabic, Hebrew, Persian or Urdu labels, pass false so shaping is correct from the very first render.