> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ios/maps/llms.txt)

# Set a style

When adding a map to an iOS application using the Maps SDK, the map's style dictates the visual design of the map, including colors, labels, and feature visibility. It also includes information about data sources, and is used by the SDK to fetch the appropriate data necessary to render the map.

![An iOS application displaying a map using the Mapbox Standard style.](https://docs.mapbox.com/ios/assets/ideal-img/maps-guides-eiffel-standard-style.418c641.480.png)

![](https://docs.mapbox.com/ios/assets/ideal-img/beta-maps-guides-outdoors.3f52188.480.png)

![](https://docs.mapbox.com/ios/assets/ideal-img/beta-maps-guides-3d-terrain.82c6563.480.png)

By default the Maps SDK for iOS uses the [Mapbox Standard](https://docs.mapbox.com/map-styles/standard/guides/) style, which is a versatile and visually appealing map style suitable for many applications. Mapbox Standard offers many [configuration options](https://docs.mapbox.com/map-styles/standard/api/#configuration-properties), allowing developers to customize the map's appearance to suit the needs of their application. If a completely unique look and feel is needed for the map, developers can create custom styles using [Mapbox Studio](https://docs.mapbox.com/console-tools/studio/), which can then be loaded into the map.

Once a style is loaded, you can continue to manipulate it at runtime, changing the appearance of the map by changing style configurations, adding or removing layers, changing layer properties, and more. This guide explains how to set and configure a style when initializing a map and how to switch styles dynamically during runtime.

## Load a style

The Maps SDK provides an embeddable map interface using [`Map`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/map/) in SwiftUI or [`MapView`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapview/) in UIKit. To render a map in the `Map` or `MapView`, you will need to determine which style the renderer should use. You can rely on the Mapbox Standard Style which is loaded by default, or you can specify another style.

### Mapbox Standard

[Mapbox Standard](https://docs.mapbox.com/map-styles/standard/) is our general-purpose map style that is designed to be used in a wide range of applications, suitable for most use cases and includes a variety of configuration options to customize the map's appearance.

Mapbox Standard is the default style, and instantiating a [`Map`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/map/) or[`MapView`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapview/) without specifying any style means your map will use Mapbox Standard.

**SwiftUI**

```swift
// Loads Mapbox Standard Style by default.
Map()
```

**UIKit**

```swift
// Loads Mapbox Standard Style by default.
mapView = MapView(frame: view.bounds)
```

You can explicitly set Mapbox Standard as the style for your map using [`MapStyle.standard`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapstyle/standard/) in SwiftUI or [`StyleURI.standard`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/styleuri/standard/) in UIKit:

**SwiftUI**

```swift
Map().mapStyle(.standard())
```

**UIKit**

```swift
mapView = MapView(
  frame: view.bounds,
  mapInitOptions: MapInitOptions(styleURI: .standard))
```

### Custom styles

You can also create your own custom styles using the Mapbox Studio style editor. Custom styles can be used to create a unique look and feel for your map, tailored to your application's design needs. You can use Mapbox Standard edited in Mapbox Studio or any other style as a base—or start from scratch entirely. Learn how to customize Standard in [this tutorial](https://docs.mapbox.com/help/tutorials/configure-basemap-mapbox-studio/), how to build a style from scratch [in this guide](https://docs.mapbox.com/help/dive-deeper/map-design/#how-to-create-a-custom-style) or explore our style [gallery](https://www.mapbox.com/gallery).

You can specify a style to use when you instantiate a map using a Style URL, a Style Constant, or a Style JSON string.

#### Load a style using a Style URL

All Mapbox styles and custom styles created in Mapbox Studio have a unique style URL starting with `mapbox://`. You can use this URL as a `StyleURI` when initializing a map:

**SwiftUI**

```swift
Map()
  .mapStyle(MapStyle(uri: StyleURI(rawValue: "mapbox://styles/your-mapbox-username/your-custom-style-url")!))
```

**UIKit**

```swift
MapView(
    frame: view.bounds,
    mapInitOptions: MapInitOptions(
      styleURI: StyleURI(rawValue: "mapbox://styles/your-mapbox-username/your-custom-style-url")!))
```

#### Load a Mapbox style using a Style Constant

If you are using a Mapbox-designed style, you can use [style constants](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/styleuri/) instead of the full style URL. This will also make sure you're using the latest version of the style:

| Style Name | SDK Constant |
| --- | --- |
| Mapbox Standard | [`MapStyle.standard`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapstyle/standard/) |
| Mapbox Standard Satellite | [`MapStyle.standardSatellite`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapstyle/standardsatellite/) |

**SwiftUI**

```swift
Map()
  .mapStyle(.standardSatellite)
```

**UIKit**

```swift
MapView(
    frame: view.bounds,
    mapInitOptions: MapInitOptions(
      styleURI: .standardSatellite))
```

> **Note: Loading a Style using Style JSON**
> 
> Though less common, you can also use [`MapStyle(json:configuration:)`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapstyle/init(json:configuration:)) to load a style if you've written style JSON manually. If your style is bundled with the app, use [`MapStyle(uri:configuration:)`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapstyle/init(uri:configuration:)) with the URI of the Style JSON file.

### Delay setting the style

If you want to initialize the map but delay loading a style until after the map is displayed on the UI, you can or use `MapStyle.empty` in SwiftUI or `StyleURI.none` in UIKit:

**SwiftUI**

```swift
Map()
  .mapStyle(MapStyle(.empty))
```

**UIKit**

```swift
MapView(
    frame: view.bounds,
    mapInitOptions: MapInitOptions(
      styleURI: .none))
```

In the case above, the map is rendered with solid black background color by default. If you want to adjust the color of the map's background to fit your design before your style is loaded, you can create a minimal style JSON string with a background layer set to the desired color.

**SwiftUI**

```swift
let styleJSON = """
{
  "version": 8,
  "sources": {},
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": {
        "background-color": "hsl(100, 50%, 50%)"
      }
    }
  ]
}
"""

Map(initialViewport: .camera(center: center, zoom: 2, bearing: 0, pitch: 0))
    .mapStyle(.init(json: styleJSON))
```

**UIKit**

```swift
let styleJSON = """
{
  "version": 8,
  "sources": {},
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": {
        "background-color": "hsl(100, 50%, 50%)"
      }
    }
  ]
}
"""


let mapView = MapView(
    frame: view.bounds,
    mapInitOptions: MapInitOptions(styleJSON: styleJSON)
)
```

## Configure a style

Depending on which map style you choose, you have different configuration options available to customize aspects of your style such as fonts, colors, and more.

### Mapbox Standard

**Mapbox Standard** and **Mapbox Standard Satellite** are our default, all-purpose map styles, and are recommended for most use cases. These styles provide a limited set of configurations instead of allowing for full manipulation of the style.

Each style can be configured with several options, including [light presets](https://docs.mapbox.com/map-styles/standard/guides/#light-presets), [label visibility](https://docs.mapbox.com/map-styles/standard/guides/#label-visibility), [feature visibility](https://docs.mapbox.com/map-styles/standard/guides/#feature-visibility), [color theming](https://docs.mapbox.com/map-styles/standard/guides/#theming), and [fonts](https://docs.mapbox.com/map-styles/standard/guides/#fonts), and more. You can set these at runtime by passing in parameters to [`MapStyle.standard`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapstyle/standard/) or [`MapStyle.standardSatellite`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapstyle/standardsatellite/). You can also use the [`setStyleImportConfigProperty`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/stylemanager/setstyleimportconfigproperty(for:config:value:)/) method to set the configuration properties for any style.

> **Related content (playground): [Mapbox Standard Style Playground](https://docs.mapbox.com/playground/standard-style/)**
> 
> Using this interactive tool, you can see in real-time how different configuration options affect the Mapbox Standard or Mapbox Standard Satellite styles.

All configuration properties for Mapbox Standard are also available for Mapbox Standard Satellite except for toggling 3D objects and color theming. To learn more about configuration options, refer to the [Mapbox Standard Guide](https://docs.mapbox.com/map-styles/standard/guides/#configuration) and the [Mapbox Standard API Reference Docs](https://docs.mapbox.com/map-styles/standard/api/#configuration-properties).

The following sample code shows how to change the 3D lights from the default preset, `day`, to another preset, `dusk`, by setting the `lightPreset` configuration. The code also shows how to hide the point of interest labels by setting the `showPlaceLabels` configuration to `false`.

**SwiftUI**

```swift
Map()
  .mapStyle(.standard(lightPreset: .dusk, showPlaceLabels: false))
```

**UIKit**

```swift
let mapView = MapView(
    frame: view.bounds
)
mapView.mapboxMap.mapStyle = .standard(
    lightPreset: .dusk,
    showPlaceLabels: false
)
```

### Custom styles

Custom styles can be configured by calling methods to update the properties of the style. The most common configurations are updates to layer properties, such as changing the color of a line or the visibility of a label.

For example, you may want to hide an existing layer by setting its `visibility` to `none`, or change the color of a `fill` layer by setting its `fill-color` property. Learn more about updating layers in the [Work with sources and layers](https://docs.mapbox.com/ios/maps/guides/styles/work-with-layers/#update-a-layer-at-runtime) guide.

This approach requires knowing the ids and types of layers in the style and understanding the properties that can be updated for each layer type. You can explore the properties available for a given layer type in the [Mapbox Style Specification](https://docs.mapbox.com/style-spec/reference/).

An alternative approach to adding many runtime configuration changes for a style is to create a custom style in [Mapbox Studio](https://docs.mapbox.com/console-tools/studio/). You can make the desired changes in the style editor and load the custom style in your application.

**SwiftUI**

```swift
// use MapReader to expose the MapboxMap instance
  MapReader { proxy in
    Map()
        .mapStyle(.streets)
        .onMapLoaded { _ in
            do {
                // set the fill color of the "water" layer to #45d9ca
                try proxy.map?.setLayerProperty(
                  for: "water",
                  property: "fill-color",
                  value: "#45d9ca")
            } catch {
                print("Error setting layer property: (error)")
            }
        }
    
}
```

**UIKit**

```swift
let mapView = MapView(
    frame: view.bounds,
    mapInitOptions: MapInitOptions(
        styleURI: .streets
    )
)

mapLoadedToken = mapView.mapboxMap.onMapLoaded.observeNext { [weak self] _ in
    guard let self = self else { return }

    // Attempt to modify the "water" layer color
    do {
        try mapView.mapboxMap.setLayerProperty(
            for: "water",
            property: "fill-color",
            value: "#45d9ca"
        )
    } catch {
        print("Failed to set layer property: (error)")
    }
}
```

## Change to a different style

You can change the style any time after initializing the map using the `MapboxMap` [`loadStyle`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapboxmap/loadstyle(_:transition:reloadpolicy:completion:)-268d9/) method.

**SwiftUI**

```swift
MapReader { proxy in
    Map()
        .mapStyle(.standard)
        .onMapLoaded { _ in
            proxy.map?.loadStyle(.standardSatellite)
        }
    
}
```

**UIKit**

```swift
mapView.mapboxMap.loadStyle(.standardSatellite)
```

If you added any layers after the map was initialized, you will need to re-add them after the new style is loaded *or* use the [`addPersistentLayer`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/stylemanager/addpersistentlayer(_:layerposition:)/) method when adding any layers to the initial style.