Switch language of your Mapbox GL JS style
Clone or download


Mapbox GL Language Build Status npm

Adds support for switching the language of your map style in Mapbox GL JS maps.

Requires mapbox-gl-js. For other platforms, such as Android and iOS, see this help document.

Multiple language supported with style transforms

Automatic style transformations for different languages

Switch language based on user agent

Switch language based on user agent


mapbox-gl-language is a Mapbox GL JS plugin that you can easily add on top of your map.

When using a CDN

<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-language/v0.10.0/mapbox-gl-language.js'></script>

When using modules

Check how to use Mapbox GL JS in a module bundler.

npm install --save mapbox-gl @mapbox/mapbox-gl-language
var mapboxgl = require('mapbox-gl')
var MapboxLanguage = require('@mapbox/mapbox-gl-language');


mapboxgl.accessToken = 'YOUR_ACCESS_TOKEN';
var map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v10',
    center: [-77.0259, 38.9010],
    zoom: 9

// Add RTL support if you want to support Arabic
// mapboxgl.setRTLTextPlugin('https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.1.0/mapbox-gl-rtl-text.js');

var language = new MapboxLanguage();

Check examples/ for more usage examples.



Create a new Mapbox GL JS plugin that modifies the layers of the map style to use the 'text-field' that matches the browser language.


  • options object Options to configure the plugin.
    • options.supportedLanguages Array<string>? List of supported languages
    • options.languageTransform Function? Custom style transformation to apply
    • options.languageField RegExp? RegExp to match if a text-field is a language field (optional, default /^\{name/)
    • options.getLanguageField Function? Given a language choose the field in the vector tiles
    • options.languageSource string? Name of the source that contains the different languages.
    • options.defaultLanguage string? Name of the default language to initialize style after loading.


Explicitly change the language for a style.


  • style object Mapbox GL style to modify
  • language string The language iso code

Returns object the modified style


Run the linter and watch for changes to rebuild with browserify.

npm install
npm run test


Showcasing the languages supported by Mapbox Streets.

Supported Styles

You can configure the plugin to support your own very custom style using style transforms and custom language fields. By default this plugin works best with official Mapbox styles (or styles derived from official Mapbox styles):

  • mapbox://mapbox-streets-v10
  • mapbox://mapbox-outdoors-v10
  • mapbox://mapbox-dark-v9
  • mapbox://mapbox-light-v9
  • mapbox://mapbox-satellite-streets-v9
  • mapbox://mapbox-traffic-day-v2
  • mapbox://mapbox-traffic-night-v2