Skip to main content

Migrating to Mapbox Standard

Mapbox Standard is the recommended style for all new projects, offering 3D buildings, dynamic lighting, featuresets for interactivity, and continuously improving cartography. This guide covers two common migration paths from classic styles.

Scenario 1: Swapping a classic style on map initialization​

If your application loads a Mapbox classic style and then adds custom sources and layers (or manipulates the style at runtime), you can migrate by swapping the style URL and updating a few patterns.

Step 1: Replace the style URL or style constant​

Replace the classic style URL or style constant with Mapbox Standard or Mapbox Standard Satellite:

Replace the style URL
// Before — classic style
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/light-v11',
  center: [-74.006, 40.7128],
  zoom: 12,
});

// After — Mapbox Standard
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/standard',
  center: [-74.006, 40.7128],
  zoom: 12,
});

Step 2: Use slots instead of before when adding runtime layers​

When adding runtime layers to classic styles, you may have specified a before layer ID to control the layer's position in the stack. With Mapbox Standard, the internal layers are not directly accessible, so you can no longer specify a before layer ID. Instead, Mapbox Standard provides named slots for this purpose: bottom, middle, and top.

Replace any use of before with the appropriate slot value based on where you want the layer to appear in the layer stack relative to the basemap's internal layers:

Use slots instead of before
// Before — classic style
map.addLayer({
  id: 'my-layer',
  type: 'fill',
  source: 'my-source',
  // ...
}, 'road-label'); // inserted before this layer

// After — Mapbox Standard
map.addLayer({
  id: 'my-layer',
  type: 'fill',
  source: 'my-source',
  slot: 'middle', // inserted above roads, behind 3D buildings
  // ...
});
SlotPosition
bottomAbove polygons (land, landuse, water), below roads
middleAbove roads, behind 3D buildings
topAbove POI labels, behind place and transit labels

Step 3: Initialize the map with configuration properties​

With classic styles, you may have manipulated layer visibility or styling properties at runtime to achieve a certain look (for example, hiding POI labels or changing the color of water features). With Mapbox Standard, you can achieve these customizations using the style's configuration properties instead of manipulating individual layers.

Instead of manually hiding or restyling classic style layers, use Mapbox Standard's configuration properties to control the style's appearance. Specify configuration properties when the map is initialized:

Use configuration properties instead of layer manipulation
// Before — classic style, manually hiding a layer
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/light-v11',
});
map.on('load', () => {
  map.setLayoutProperty('poi-label', 'visibility', 'none');
});

// After — configure Mapbox Standard during map initialization
// Remove any existing manipulation of the classic style's layers
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/standard',
  config: {
      basemap: {
          lightPreset: 'dusk',
          showPointOfInterestLabels: false,
      }
  }
});

See the Mapbox Standard Style reference for the full list of configuration options including light presets, color overrides, and feature visibility toggles.

Step 4: Update any runtime style manipulation​

With classic styles, you may have wired up UI controls — such as toggles or buttons — to directly manipulate style layers at runtime. For example, a "hide POI labels" toggle might update the visibility of an internal label layer, or a theme switcher might update the color of road or water layers. Since Mapbox Standard's internal layers are not directly accessible, this pattern no longer works.

Remove any runtime calls that target classic style layer IDs, and replace them with calls to update Standard's configuration properties:

Update configuration at runtime
// Before — classic style, manipulating internal layers at runtime
map.setLayoutProperty('poi-label', 'visibility', 'none');
map.setPaintProperty('water', 'fill-color', '#000');

// After — Mapbox Standard, update configuration properties at runtime
map.setConfigProperty('basemap', 'lightPreset', 'dusk');
map.setConfigProperty('basemap', 'showPointOfInterestLabels', false);
Layers you add can be fully controlled

Layers you add to the map at runtime are still fully controllable. Only the Standard Style's internal layers are restricted.

Scenario 2: Migrating a custom style​

If you created a custom style by cloning a classic style in Mapbox Studio, you can migrate by replacing the layer stack with a Mapbox Standard import.

Step 1: Remove classic style layers in Mapbox Studio​

Open your custom style in Mapbox Studio. Delete all layers that originated from the classic style, keeping only the custom layers and data sources you added.

Step 2: Add a Mapbox Standard import​

In Mapbox Studio, add a style import and point it to Mapbox Standard or Mapbox Standard Satellite:

  • Mapbox Standard — mapbox://styles/mapbox/standard
  • Mapbox Standard Satellite — mapbox://styles/mapbox/standard-satellite

Once the import is added, use the Mapbox Studio UI to configure the imported style's properties — such as light preset, label visibility, and color overrides — without needing to edit the style JSON directly. These settings are equivalent to the configuration properties you can set at runtime in code.

Step 3: Assign slots to your custom layers​

With Mapbox Standard imported as the basemap, assign each of your remaining custom layers to the appropriate slot (bottom, middle, or top) using Mapbox Studio's layer ordering controls.

Step 4: Update any runtime style manipulation​

With classic styles, you may have wired up UI controls — such as toggles or buttons — to directly manipulate style layers at runtime. For example, a "hide POI labels" toggle might update the visibility of an internal label layer, or a theme switcher might update the color of road or water layers. Since Mapbox Standard's internal layers are not directly accessible, this pattern no longer works.

Remove any runtime calls that target classic style layer IDs, and replace them with calls to update Standard's configuration properties:

Update configuration at runtime
// Before — classic style, manipulating internal layers at runtime
map.setLayoutProperty('poi-label', 'visibility', 'none');
map.setPaintProperty('water', 'fill-color', '#000');

// After — Mapbox Standard, update configuration properties at runtime
map.setConfigProperty('basemap', 'lightPreset', 'dusk');
map.setConfigProperty('basemap', 'showPointOfInterestLabels', false);

Additional resources​

Was this page helpful?