Set a style | Maps SDK for Flutter | Mapbox Docs

Across the Mapbox ecosystem, the appearance of the map is determined by the map style. A Mapbox style is a JSON object that defines exactly how to draw a map. It defines almost everything related to a map's appearance. In the Maps SDK, you will set the style of the map after initializing the map view.

Choose a style

The style you choose for your application should reflect how your users will interact with the map and what they will use your application for. If you are not sure what style is right for you, we recommend getting started with the carefully designed, all-purpose Mapbox Standard style or Mapbox Standard Satellite.

Mapbox Standard

Mapbox Standard is the default style, and instantiating a map without specifying any style means your map will use Mapbox Standard.


// Loads Mapbox Standard Style by default.
MapWidget();

Load a specific style

You can specify the initial style URI with MapWidget.styleUri, or load it at runtime using MapboxMap.loadStyleURI:


MapWidget(styleUri: MapboxStyles.SATELLITE);


mapboxMap.loadStyleURI(MapboxStyles.LIGHT);

Using constants will also make sure you’re using the latest version of the style:

Mapbox Standard: MapboxStyles.standard
Mapbox Standard Satellite: MapboxStyles.standardSatellite
Mapbox Streets: MapboxStyles.streets
Mapbox Outdoors: MapboxStyles.outdoors
Mapbox Satellite: MapboxStyles.satellite
Mapbox Satellite Streets: MapboxStyles.satelliteStreets
Mapbox Light: MapboxStyles.light
Mapbox Dark: MapboxStyles.dark

Additionally, you can load a custom style built in Mapbox Studio using a Mapbox Style URL


mapboxMap.loadStyleURI("mapbox://styles/<user>/<style>");

Use loadStyleJSON

Though less common, you can also use MapboxMap.loadStyleJson to load a style if you've written your style JSON manually.

Configure a style

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

Mapbox Standard and Mapbox Standard Satellite

The underlying design paradigm to Mapbox Standard and Mapbox Standard Satellite is different from what you know from the classic styles templates. We’re establishing the concept of a basemap; Mapbox Standard and Mapbox Standard Satellite are being the first ones to follow this paradigm. You can consider everything that is maintained by Mapbox (natural features, roads, buildings etc.) as the basemap into which you embed your custom layers. The differentiation is important because different rules apply to the basemap and custom layers.

The Standard style offers 8 configuration properties for developers to change when they import it into their own style:

Property	Type	Description
`showPlaceLabels`	`Bool`	Shows and hides place label layers.
`showRoadLabels`	`Bool`	Shows and hides all road labels, including road shields.
`showPointOfInterestLabels`	`Bool`	Shows or hides all POI icons and text.
`showTransitLabels`	`Bool`	Shows or hides all transit icons and text.
`show3dObjects`	`Bool`	Shows or hides all 3D layers (3D buildings, landmarks, trees, etc.) including shadows, ambient occlusion, and flood lights.
`theme`	`String`	Switches between 3 themes: `default`, `faded` and `monochrome`.
`lightPreset`	`String`	Switches between 4 time-of-day states: `dusk`, `dawn`, `day`, and `night`. Lights can also be fully customized beyond the presets using the Mapbox style specification.
`font`	`String`	Defines font family for the style from predefined options. Options: `Alegreya`, `Alegreya SC`, `Asap`, `Barlow`, `DIN Pro`, `EB Garamond`, `Faustina`, `Frank Ruhl Libre`, `Heebo`, `Inter`, `League Mono`, `Montserrat`, `Poppins`, `Raleway`, `Roboto`, `Roboto Mono`, `Rubik`, `Source`, `Code Pro`, `Spectral`, `Ubuntu`, `Noto Sans CJK JP`, `Open Sans`, `Manrope`, `Source Sans Pro`, `Lato`

The Standard Satellite Style (mapbox://styles/mapbox/standard-satellite) combines updated satellite imagery and vector layers to offer users improved clarity and detail. Like Standard style, the Satellite Style receives all updates automatically and also supports light presets. Additionally, it introduces two new configurations showRoadsAndTransit and showPedestrianRoads. Users can now choose to hide roads, simplifying the map style for a better focus on specific areas or features.

The Standard Satellite style offers 8 configuration properties for developers to change when they import it into their own style:

Property	Type	Description
`showRoadsAndTransit`	`Bool`	Shows and hides all roads and transit networks.
`showPedestrianRoads`	`Bool`	Shows and hides all pedestrian roads, paths, trails.
`showPlaceLabels`	`Bool`	Shows and hides place label layers.
`showRoadLabels`	`Bool`	Shows and hides all road labels, including road shields.
`showPointOfInterestLabels`	`Bool`	Shows or hides all POI icons and text.
`showTransitLabels`	`Bool`	Shows or hides all transit icons and text.
`lightPreset`	`String`	Switches between 4 time-of-day states: `dusk`, `dawn`, `day`, and `night`.
`font`	`String`	Defines font family for the style from predefined options.
Important: Standard satellite style doesn't support `theme` and `show3dObjects` configuration.

Here’s an example illustrating how to switch the 3D lights from the default preset, day, to another preset, dusk.


mapboxMap.style.setStyleImportConfigProperty("basemap", "lightPreset", "dusk");

Similarly, you can set other configuration properties on the Standard styles such as showing POIs, place labels, or specific fonts:


mapboxMap.style.setStyleImportConfigProperty("basemap", "showPointOfInterestLabels", false);

Other options to customize your map using Mapbox Standard and Mapbox Standard Satellite are by configuring root properties, or styling your custom data such that it reflects your personal preferences. Note that all the configurations are also available in the Mapbox Studio.

For custom layers that you add to the Mapbox Standard basemap, all configuration options are defined in the Mapbox Style Specification.

Mapbox Standard Satellite

The Standard Satellite style supports 8 configuration options, but with some differences. It includes 2 additional settings for showing and hiding the road network. Unlike the Standard style, it does not support the theme and show3dObjects configurations:

Property	Type	Description
`showRoadsAndTransit`	`Bool`	Shows and hides all roads and transit networks.
`showPedestrianRoads`	`Bool`	Shows and hides all pedestrian roads, paths, trails.
`showPlaceLabels`	`Bool`	Shows and hides place label layers.
`showRoadLabels`	`Bool`	Shows and hides all road labels, including road shields.
`showPointOfInterestLabels`	`Bool`	Shows or hides all POI icons and text.
`showTransitLabels`	`Bool`	Shows or hides all transit icons and text.
`lightPreset`	`String`	Switches between 4 time-of-day states: `dusk`, `dawn`, `day`, and `night`. Lights can also be fully customized beyond the presets using the Mapbox style specification.
`font`	`String`	Defines font family for the style from predefined options. Options: `Alegreya`, `Alegreya SC`, `Asap`, `Barlow`, `DIN Pro`, `EB Garamond`, `Faustina`, `Frank Ruhl Libre`, `Heebo`, `Inter`, `League Mono`, `Montserrat`, `Poppins`, `Raleway`, `Roboto`, `Roboto Mono`, `Rubik`, `Source`, `Code Pro`, `Spectral`, `Ubuntu`, `Noto Sans CJK JP`, `Open Sans`, `Manrope`, `Source Sans Pro`, `Lato`

Style imports

To work with styles like Mapbox Standard and Mapbox Standard Satellite, we've introduced Style APIs that allow you to import other styles into the main style you display to your users. These styles will be imported by reference, so updates to them will be reflected in your main style without additional work needed on your side. For example, imagine you have style A and style B. The Style API will allow you to import A into B. Upon importing, you can set configurations that apply to A and adjust them at runtime. The configuration properties for the imported style A will depend on what the creator of style A chooses to be configurable. For Standard styles, 8 configuration properties are available for setting lighting, fonts, and label display options. To import a style, you need to add an imports property to your Style JSON. In the above example, you would add "imports" to your Style JSON for B to import style A and set various configurations as defined in style A in the schema root property.


...
"imports": [
    {
        "id": "A",
        "url": "STYLE_URL_FOR_A",
        "config": {
            "theme": "faded",
            "font": "Montserrat",
            "lightPreset": "dusk",
            "theme": "default",
            "show3dObjects": true,
            "showPointOfInterestLabels": true,
            "showTransitLabels": false,
            "showPlaceLabels": true,
            "showRoadLabels": false,
            "show3dObjects": true
        }
    }
],
...

mapboxMap.style.getStyleImports(), which returns all the styles you have imported into your main style
mapboxMap.style.removeStyleImport(), which removes the style import with the passed Id
mapboxMap.style.getStyleImportSchema(), which returns the full schema describing the style import with the passed Id
mapboxMap.style.getStyleImportConfigProperties(), which returns all the configuration properties of the style import with the passed Id
mapboxMap.style.getStyleImportConfigProperty(), which returns the specified configuration property of the style import with the passed Id
mapboxMap.style.setStyleImportConfigProperties(), which sets all the configuration properties of the style import with the passed Id
mapboxMap.style.setStyleImportConfigProperty(), which sets the specified configuration property of the style import with the passed Id

Classic style templates and custom styles

The configuration options for classic style templates and custom styles are defined in the Mapbox Style Specification. Note that all the configurations are also available in the Mapbox Studio.

Additional Developer Resources

Mapbox Developer Discord

Developer Cheatsheet

Mapbox Support

Ask AI

Was this page helpful?