Configure the Basemap at Runtime | Mapbox GL JS

Upgrade to Mapbox GL JS v3

This feature is available in Mapbox GL JS v3. Learn how to migrate in our migrate to v3 guide

The Mapbox Standard Style exposes configuration properties that let you control the basemap's look and feel — including lighting presets and label visibility for POIs, transit, places, and roads — without reloading the style. This example shows a UI that calls setConfigProperty whenever the user makes a selection.

Explore all Standard Style configuration properties

Explore all configuration options and see how they affect the map's appearance in the Standard Style Playground.

For the full list of options, see the Mapbox Standard Style documentation.

If you want to set up these settings before the map first renders rather than updating them after load, see the Configure the basemap during Map Initialization example.

JavaScript

React

JavaScript

React


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Configure the Basemap at Runtime</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<style>
    .map-overlay {
        font:
            12px/20px 'Helvetica Neue',
            Arial,
            Helvetica,
            sans-serif;
        position: absolute;
        width: 200px;
        top: 0;
        left: 0;
        padding: 10px;
    }

    .map-overlay .map-overlay-inner {
        background-color: #fff;
        box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
        border-radius: 3px;
        padding: 10px;
        margin-bottom: 10px;
    }

    .map-overlay-inner fieldset {
        display: flex;
        justify-content: space-between;
        border: none;
    }

    .map-overlay-inner label {
        font-weight: bold;
        margin-right: 10px;
    }

    .map-overlay-inner .select-fieldset {
        display: block;
    }

    .map-overlay-inner .select-fieldset label {
        display: block;
        margin-bottom: 5px;
    }

    .map-overlay-inner .select-fieldset select {
        width: 100%;
    }
</style>

<div id="map"></div>

<div class="map-overlay top">
    <div class="map-overlay-inner">
        <fieldset class="select-fieldset">
            <label>Select light preset</label>
            <select id="lightPreset" name="lightPreset">
                <!-- Each value matches a light preset -->
                <option value="dawn">Dawn</option>
                <option value="day" selected="">Day</option>
                <option value="dusk">Dusk</option>
                <option value="night">Night</option>
            </select>
        </fieldset>
        <fieldset>
            <label for="showPlaceLabels">Show place labels</label>
            <input type="checkbox" id="showPlaceLabels" checked="">
        </fieldset>
        <fieldset>
            <label for="showPointOfInterestLabels">Show POI labels</label>
            <input type="checkbox" id="showPointOfInterestLabels" checked="">
        </fieldset>
        <fieldset>
            <label for="showRoadLabels">Show road labels</label>
            <input type="checkbox" id="showRoadLabels" checked="">
        </fieldset>
        <fieldset>
            <label for="showTransitLabels">Show transit labels</label>
            <input type="checkbox" id="showTransitLabels" checked="">
        </fieldset>
    </div>
</div>

<script>
    const map = new mapboxgl.Map({
        // TO MAKE THE MAP APPEAR YOU MUST
        // ADD YOUR ACCESS TOKEN FROM
        // https://account.mapbox.com
        accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
        container: 'map', // container ID
        center: [2.2932, 48.86069], // starting position [lng, lat]
        zoom: 15.1, // starting zoom
        pitch: 62, // starting pitch
        bearing: -20, // starting bearing
        style: 'mapbox://styles/mapbox/standard' // style URL
    });

    map.on('style.load', () => {
        map.addSource('line', {
            type: 'geojson',
            lineMetrics: true,
            data: {
                type: 'LineString',
                coordinates: [
                    [2.293389857555951, 48.85896319631851],
                    [2.2890810326441624, 48.86174223718291]
                ]
            }
        });

        map.addLayer({
            id: 'line',
            source: 'line',
            type: 'line',
            paint: {
                'line-width': 12,
                // The `*-emissive-strength` properties control the intensity of light emitted on the source features.
                // To enhance the visibility of a line in darker light presets, increase the value of `line-emissive-strength`.
                'line-emissive-strength': 0.8,
                'line-gradient': [
                    'interpolate',
                    ['linear'],
                    ['line-progress'],
                    0,
                    'red',
                    1,
                    'blue'
                ]
            }
        });
    });

    document
        .getElementById('lightPreset')
        .addEventListener('change', function () {
            map.setConfigProperty('basemap', 'lightPreset', this.value);
        });

    document
        .querySelectorAll('.map-overlay-inner input[type="checkbox"]')
        .forEach((checkbox) => {
            checkbox.addEventListener('change', function () {
                map.setConfigProperty('basemap', this.id, this.checked);
            });
        });
</script>

</body>
</html>

This code snippet will not work as expected until you replace YOUR_MAPBOX_ACCESS_TOKEN with an access token from your Mapbox account.

JavaScript

React


import React, { useState, useEffect, useRef } from 'react';
import mapboxgl from 'mapbox-gl';

import 'mapbox-gl/dist/mapbox-gl.css';

const MapboxExample = () => {
  const mapContainerRef = useRef();
  const mapRef = useRef();

  const [lightPreset, setLightPreset] = useState('day');
  const [showPlaceLabels, setShowPlaceLabels] = useState(true);
  const [showPOILabels, setShowPOILabels] = useState(true);
  const [showRoadLabels, setShowRoadLabels] = useState(true);
  const [showTransitLabels, setShowTransitLabels] = useState(true);
  const [styleLoaded, setStyleLoaded] = useState(false);

  useEffect(() => {
    mapRef.current = new mapboxgl.Map({
      // TO MAKE THE MAP APPEAR YOU MUST
      // ADD YOUR ACCESS TOKEN FROM
      // https://account.mapbox.com
      accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
      container: mapContainerRef.current,
      center: [2.2932, 48.86069],
      zoom: 15.1,
      pitch: 62,
      bearing: -20
    });

    mapRef.current.on('style.load', () => {
      setStyleLoaded(true);

      mapRef.current.addSource('line', {
        type: 'geojson',
        lineMetrics: true,
        data: {
          type: 'LineString',
          coordinates: [
            [2.293389857555951, 48.85896319631851],
            [2.2890810326441624, 48.86174223718291]
          ]
        }
      });

      mapRef.current.addLayer({
        id: 'line',
        source: 'line',
        type: 'line',
        paint: {
          'line-width': 12,
          'line-emissive-strength': 0.8,
          'line-gradient': [
            'interpolate',
            ['linear'],
            ['line-progress'],
            0,
            'red',
            1,
            'blue'
          ]
        }
      });
    });

    return () => mapRef.current.remove();
  }, []);

  useEffect(() => {
    if (!styleLoaded) return;

    mapRef.current.setConfigProperty('basemap', 'lightPreset', lightPreset);
    mapRef.current.setConfigProperty(
      'basemap',
      'showPlaceLabels',
      showPlaceLabels
    );
    mapRef.current.setConfigProperty(
      'basemap',
      'showPointOfInterestLabels',
      showPOILabels
    );
    mapRef.current.setConfigProperty(
      'basemap',
      'showRoadLabels',
      showRoadLabels
    );
    mapRef.current.setConfigProperty(
      'basemap',
      'showTransitLabels',
      showTransitLabels
    );
  }, [
    lightPreset,
    showPlaceLabels,
    showPOILabels,
    showRoadLabels,
    showTransitLabels
  ]);

  const mapOverlayStyle = {
    font: "12px/20px 'Helvetica Neue', Arial, Helvetica, sans-serif",
    position: 'absolute',
    width: '200px',
    top: '0',
    left: '0',
    padding: '10px'
  };

  const mapOverlayInnerStyle = {
    backgroundColor: '#fff',
    boxShadow: '0 1px 2px rgba(0, 0, 0, 0.1)',
    borderRadius: '3px',
    padding: '10px',
    marginBottom: '10px'
  };

  const fieldsetStyle = {
    display: 'flex',
    justifyContent: 'space-between',
    border: 'none'
  };

  const labelStyle = {
    fontWeight: 'bold',
    marginRight: '10px'
  };

  const selectFieldsetStyle = {
    display: 'block',
    border: 'none'
  };

  const selectLabelStyle = {
    display: 'block',
    marginBottom: '5px',
    fontWeight: 'bold'
  };

  const selectStyle = {
    width: '100%'
  };

  return (
    <>
      <div ref={mapContainerRef} style={{ height: '100%' }} />;
      <div className="map-overlay" style={mapOverlayStyle}>
        <div className="map-overlay-inner" style={mapOverlayInnerStyle}>
          <fieldset className="select-fieldset" style={selectFieldsetStyle}>
            <label style={selectLabelStyle}>
              Select light preset
              <select
                id="lightPreset"
                name="lightPreset"
                value={lightPreset}
                onChange={(e) => setLightPreset(e.target.value)}
                style={selectStyle}
              >
                <option value="dawn">Dawn</option>
                <option value="day">Day</option>
                <option value="dusk">Dusk</option>
                <option value="night">Night</option>
              </select>
            </label>
          </fieldset>
          <fieldset style={fieldsetStyle}>
            <label style={labelStyle}>
              Show place labels
              <input
                type="checkbox"
                id="showPlaceLabels"
                checked={showPlaceLabels}
                onChange={(e) => setShowPlaceLabels(e.target.checked)}
              />
            </label>
          </fieldset>
          <fieldset style={fieldsetStyle}>
            <label style={labelStyle}>
              Show POI labels
              <input
                type="checkbox"
                id="showPointOfInterestLabels"
                checked={showPOILabels}
                onChange={(e) => setShowPOILabels(e.target.checked)}
              />
            </label>
          </fieldset>
          <fieldset style={fieldsetStyle}>
            <label style={labelStyle}>
              Show road labels
              <input
                type="checkbox"
                id="showRoadLabels"
                checked={showRoadLabels}
                onChange={(e) => setShowRoadLabels(e.target.checked)}
              />
            </label>
          </fieldset>
          <fieldset style={fieldsetStyle}>
            <label style={labelStyle}>
              Show transit labels
              <input
                type="checkbox"
                id="showTransitLabels"
                checked={showTransitLabels}
                onChange={(e) => setShowTransitLabels(e.target.checked)}
              />
            </label>
          </fieldset>
        </div>
      </div>
    </>
  );
};

export default MapboxExample;

This code snippet will not work as expected until you replace YOUR_MAPBOX_ACCESS_TOKEN with an access token from your Mapbox account.

Was this example helpful?