Imports
imports is a top-level style property that allows you to add the contents of other styles into the current style by reference.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
Instead of copying individual layers, only the other style's URL is referenced, so that the imported style is always the most recent version. Imported styles are rendered together with the layers in the current style. The imported layers are not directly available through runtime APIs, but you can customize them. You can customize an imported style by specifying configuration values for the imported style:
{
...
"imports": [
{
"id": "basemap",
"url": "mapbox://styles/mapbox/standard",
"config": {
"lightPreset": "dusk",
"showPointOfInterestLabels": false
}
}
]
...
}
A style can import multiple other styles, which in turn can import other styles (up to 5 levels deep).
Imported styles may define named slot layers, which act as insertion points in the imported style's layer stack. Layers in the parent style can target a slot by name, allowing them to be placed at specific positions within the imported style rather than rendering on top of it.
Import
An import description describes the style to be imported, and optionally provides configuration values to be applied to the imported style.
id
Unique import name.
url
The URL of the style.
color-theme
If specified, it overrides the color-theme of the imported style.
config
Configuration values for the imported style's options.
data
The inlined style that must correspond to the contents of the specified URL.
Config
When importing a style, you can set values for the available configuration options. If present, the value specified for the import will be used, and otherwise the option’s default value will be used.
Configuration options are used inside the imported style via ["config", "optionName"] expressions in layer properties. This allows the style author to expose customizable behavior — such as colors, visibility toggles, or other values — that consumers of the style can control through the configuration object at import time.
For example, the Mapbox Standard style defines a showPedestrianRoads configuration option. Inside the style, a layer uses a config expression to control its visibility based on this option:
{
"id": "road-pedestrian",
"type": "line",
"layout": {
"visibility": [
"case",
["config", "showPedestrianRoads"],
"visible",
"none"
]
}
}
Configuration expressions can also be used in paint properties. For example, a background layer might use ["config", "colorLand"] to allow the land color to be customized. The default value for each configuration option is defined in the style's schema, so the expression itself only needs to reference the option name:
{
"schema": {
"colorLand": {
"default": "hsl(47, 44%, 86%)",
"type": "color"
}
},
"layers": [
{
"id": "land",
"type": "background",
"paint": {
"background-color": ["config", "colorLand"]
}
}
]
}
If no value is provided for colorLand at import time, the default from the schema is used.
A consumer importing this style can then set these values:
{
"imports": [
{
"id": "basemap",
"url": "mapbox://styles/mapbox/standard",
"config": {
"showPedestrianRoads": false,
"colorLand": "#f0e8d8"
}
}
]
}
*
Value of the imported style's configuration option.
If the imported style does not have a configuration option with the specified name, the value will be ignored. The value provided in the config object will be validated against the option specified in the schema.