> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ja/map-styles/llms.txt)

# 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:

**Web**

Title: `Replace the style URL`

```js
// 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,
});
```

**Android**

Title: `Replace the style URL`

```kotlin
// Before — classic style
MapboxMap(
  style = {
      MapboxLightStyle()
  }
)

// After — Mapbox Standard
MapboxMap(
  style = {
      MapboxStandardStyle()
  }
)
```

**iOS**

Title: `Replace the style URL`

```swift
// Before — classic style
Map()
  .mapStyle(.light())

// After — Mapbox Standard
Map()
  .mapStyle(.standard())
```

**Flutter**

Title: `Replace the style URL`

```dart
// Before — classic style
MapWidget(
  styleUri: MapboxStyles.LIGHT,
)

// After — Mapbox Standard
MapWidget(
  styleUri: MapboxStyles.STANDARD,
)
```

### 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](https://docs.mapbox.com/ja/style-spec/reference/layers/#slot) 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:

**Web**

Title: `Use slots instead of before`

```js
// 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
  // ...
});
```

**Android**

Title: `Use slots instead of before`

```kotlin
// Before — classic style
MapboxMap(
  onMapLoaded = {
      mapboxMap.getStyle { style ->
          style.addLayerBelow(
              fillLayer("my-layer", "my-source") { /* ... */ },
              "road-label"
          )
      }
  }
)

// After — Mapbox Standard
MapboxMap(
  onMapLoaded = {
      mapboxMap.getStyle { style ->
          style.addLayer(
              fillLayer("my-layer", "my-source") {
                  slot(LayerSlot.MIDDLE) // inserted above roads, behind 3D buildings
              }
          )
      }
  }
)
```

**iOS**

Title: `Use slots instead of before`

```swift
// Before — classic style
Map()
  .onMapLoaded { _ in
      var layer = FillLayer(id: "my-layer", source: "my-source")
      try? mapboxMap.addLayer(layer, layerPosition: .below("road-label"))
  }

// After — Mapbox Standard
Map()
  .onMapLoaded { _ in
      var layer = FillLayer(id: "my-layer", source: "my-source")
      layer.slot = .middle // inserted above roads, behind 3D buildings
      try? mapboxMap.addLayer(layer)
  }
```

**Flutter**

Title: `Use slots instead of before`

```dart
// Before — classic style
MapWidget(
  onMapCreated: (mapboxMap) async {
      await mapboxMap.style.addLayerAt(
          FillLayer(id: "my-layer", sourceId: "my-source"),
          LayerPosition(below: "road-label"),
      );
  },
)

// After — Mapbox Standard
MapWidget(
  onMapCreated: (mapboxMap) async {
      await mapboxMap.style.addLayer(
          FillLayer(
              id: "my-layer",
              sourceId: "my-source",
              slot: LayerSlot.MIDDLE, // inserted above roads, behind 3D buildings
          ),
      );
  },
)
```

| Slot | Position |
| --- | --- |
| `bottom` | Above polygons (land, landuse, water), below roads |
| `middle` | Above roads, behind 3D buildings |
| `top` | Above 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](https://docs.mapbox.com/ja/map-styles/reference/standard/) to control the style's appearance. Specify configuration properties when the map is initialized:

**Web**

Title: `Use configuration properties instead of layer manipulation`

```js
// 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,
      }
  }
});
```

**Android**

Title: `Use configuration properties instead of layer manipulation`

```kotlin
// Before — classic style, manually hiding a layer
mapboxMap.setStyleLayerProperty("poi-label", "visibility", Value("none"))

// After — configure Mapbox Standard during map initialization
// Remove any existing manipulation of the classic style's layers
MapboxMap(
  style = {
      MapboxStandardStyle(
          standardStyleState = rememberStandardStyleState {
              configurationsState.apply {
                  lightPreset = LightPresetValue.DUSK
                  showPointOfInterestLabels = BooleanValue(false)
              }
          }
      )
  }
)
```

**iOS**

Title: `Use configuration properties instead of layer manipulation`

```swift
// Before — classic style, manually hiding a layer
try mapboxMap.setLayerProperty(for: "poi-label", property: "visibility", value: "none")

// After — configure Mapbox Standard during map initialization
// Remove any existing manipulation of the classic style's layers
Map()
  .mapStyle(.standard(lightPreset: .dusk, showPlaceLabels: false))
```

**Flutter**

Title: `Use configuration properties instead of layer manipulation`

```dart
// Before — classic style, manually hiding a layer
await mapboxMap.style.setStyleLayerProperty(
  "poi-label", "visibility", "none"
);

// After — Flutter does not support setting config properties during instantiation.
// Remove any existing manipulation of the classic style's layers,
// then set config properties once the style is loaded:
mapboxMap.style.setStyleImportConfigProperty("basemap", "lightPreset", "dusk");
mapboxMap.style.setStyleImportConfigProperty("basemap", "showPointOfInterestLabels", false);
```

See the [Mapbox Standard Style reference](https://docs.mapbox.com/ja/map-styles/reference/standard/) 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:

**Web**

Title: `Update configuration at runtime`

```js
// 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);
```

**Android**

Title: `Update configuration at runtime`

```kotlin
// Before — classic style, manipulating internal layers at runtime
mapboxMap.setStyleLayerProperty("poi-label", "visibility", Value("none"))

// After — Mapbox Standard, update configuration properties at runtime
standardStyleConfigurationState.lightPreset = LightPresetValue.DUSK
standardStyleConfigurationState.showPointOfInterestLabels = BooleanValue(false)
```

**iOS**

Title: `Update configuration at runtime`

```swift
// Before — classic style, manipulating internal layers at runtime
try mapboxMap.setLayerProperty(for: "poi-label", property: "visibility", value: "none")

// After — Mapbox Standard, update configuration properties at runtime
lightPreset = StandardLightPreset.dusk
showPlaceLabels = false
// Map().mapStyle(.standard(lightPreset: lightPreset, showPlaceLabels: showPlaceLabels))
```

**Flutter**

Title: `Update configuration at runtime`

```dart
// Before — classic style, manipulating internal layers at runtime
await mapboxMap.style.setStyleLayerProperty(
  "poi-label", "visibility", "none"
);

// After — Mapbox Standard, update configuration properties at runtime
mapboxMap.style.setStyleImportConfigProperty("basemap", "lightPreset", "dusk");
mapboxMap.style.setStyleImportConfigProperty("basemap", "showPointOfInterestLabels", false);
```

> **Note: 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](https://console.mapbox.com/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.

![Mapbox Studio UI showing style import configuration options](https://docs.mapbox.com/ja/assets/ideal-img/map-styles--studio-import-ui.653979b.480.png)

### 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.

![Mapbox Studio UI showing style import configuration options](https://docs.mapbox.com/ja/assets/ideal-img/map-styles--studio-import-ui-slot.dc20136.480.png)

### 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:

**Web**

Title: `Update configuration at runtime`

```js
// 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);
```

**Android**

Title: `Update configuration at runtime`

```kotlin
// Before — classic style, manipulating internal layers at runtime
mapboxMap.setStyleLayerProperty("poi-label", "visibility", Value("none"))

// After — Mapbox Standard, update configuration properties at runtime
standardStyleConfigurationState.lightPreset = LightPresetValue.DUSK
standardStyleConfigurationState.showPointOfInterestLabels = BooleanValue(false)
```

**iOS**

Title: `Update configuration at runtime`

```swift
// Before — classic style, manipulating internal layers at runtime
try mapboxMap.setLayerProperty(for: "poi-label", property: "visibility", value: "none")

// After — Mapbox Standard, update configuration properties at runtime
lightPreset = StandardLightPreset.dusk
showPlaceLabels = false
// Map().mapStyle(.standard(lightPreset: lightPreset, showPlaceLabels: showPlaceLabels))
```

**Flutter**

Title: `Update configuration at runtime`

```dart
// Before — classic style, manipulating internal layers at runtime
await mapboxMap.style.setStyleLayerProperty(
  "poi-label", "visibility", "none"
);

// After — Mapbox Standard, update configuration properties at runtime
mapboxMap.style.setStyleImportConfigProperty("basemap", "lightPreset", "dusk");
mapboxMap.style.setStyleImportConfigProperty("basemap", "showPointOfInterestLabels", false);
```

---

## Additional resources

-   [Mapbox Standard API Reference](https://docs.mapbox.com/ja/map-styles/reference/standard/)
-   [Mapbox Standard Satellite API Reference](https://docs.mapbox.com/ja/map-styles/reference/standard-satellite/)
-   [Slots reference](https://docs.mapbox.com/ja/style-spec/reference/layers/#slot)
-   [Style imports reference](https://docs.mapbox.com/ja/style-spec/reference/imports/)
-   [Mapbox Studio](https://console.mapbox.com/studio/)