MapMetrics Atlas API Docs

Appearance

Add Support for Right-to-Left Scripts ​

Enable correct rendering of right-to-left scripts (Arabic, Hebrew, Persian) on the map using the RTL text plugin.

Load the RTL Text Plugin ​

Call setRTLTextPlugin before creating the map instance:

javascript
mapmetricsgl.setRTLTextPlugin(
  'https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.2.3/mapbox-gl-rtl-text.min.js',
  null,   // callback on load (optional)
  true    // lazy: only loads when RTL text is encountered
);

const map = new mapmetricsgl.Map({
  container: 'map',
  style: '<StyleFile_URL_with_Token>',
});

NPM Installation ​

bash
npm install @mapbox/mapbox-gl-rtl-text
javascript
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';

mapmetricsgl.setRTLTextPlugin(
  'https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.2.3/mapbox-gl-rtl-text.min.js',
  null,
  true
);

When to Use ​

The plugin is needed whenever the map style includes labels in:

ScriptLanguage examples
ArabicArabic, Urdu
HebrewHebrew, Yiddish
PersianFarsi, Dari

Without the plugin, RTL characters render in the wrong order or direction.

Plugin Load States ​

javascript
// Check if plugin is already set
if (!mapmetricsgl.getRTLTextPluginStatus || mapmetricsgl.getRTLTextPluginStatus() === 'unavailable') {
  mapmetricsgl.setRTLTextPlugin(pluginUrl, null, true);
}

Complete Example ​

html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <link href="https://cdn.mapmetrics-atlas.net/versions/latest/mapmetrics-gl.css" rel="stylesheet" />
    <script src="https://cdn.mapmetrics-atlas.net/versions/latest/mapmetrics-gl.js"></script>
    <style>#map { height: 500px; width: 100%; }</style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      mapmetricsgl.setRTLTextPlugin(
        'https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.2.3/mapbox-gl-rtl-text.min.js',
        null,
        true
      );

      const map = new mapmetricsgl.Map({
        container: 'map',
        style: '<StyleFile_URL_with_Token>',
        center: [31.2357, 30.0444],
        zoom: 6
      });
    </script>
  </body>
</html>
jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

// Set plugin once at module level
mapmetricsgl.setRTLTextPlugin(
  'https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.2.3/mapbox-gl-rtl-text.min.js',
  null,
  true
);

const RtlSupport = () => {
  const mapContainer = useRef(null);
  const map = useRef(null);

  useEffect(() => {
    if (map.current) return;
    map.current = new mapmetricsgl.Map({
      container: mapContainer.current,
      style: '<StyleFile_URL_with_Token>',
      center: [31.2357, 30.0444],
      zoom: 6
    });
    return () => { map.current?.remove(); map.current = null; };
  }, []);

  return <div ref={mapContainer} style={{ height: '500px', width: '100%' }} />;
};

export default RtlSupport;

For more information, visit the MapMetrics GitHub repository.