Style components provide sensible defaults and quick opportunities for customization by optimizing the most common property changes for styles and packaging them into drop-down options, sliders, and toggles.
Mapbox Studio topics covered in this section:
Add data to style
A component is a collection of related map features that you style as a single unit. Components can include features of multiple types (for example fill, line, and symbol). Road network and administrative boundaries are examples of components. Each component contains several layers.
A layer is a collection of map features of a single type. bridge-pedestrian is an example of a layer. In the Mapbox Streets style, bridge-pedestrian is one of more than 50 layers in the Road network component. Layers can be a part of a component, but don’t have to be. Layers that are not part of a component are called custom layers.
Custom layers cannot be added to components or styled via a component property. They must be positioned and styled as individual, custom layers.
The term property refers to a couple different concepts in Mapbox Studio including component properties and layer properties. Both refer to options for styling map features, but vary in how they work. You can also add or remove entire components to customize your map style.
A component property is one of a few available options for styling a single component. A single component property can control multiple layer properties across several layers. Values for component properties are often defined using a toggle (on or off), a dropdown menu with a few options, or a slider with several options along a scale.
Country boundaries width is an example of a component property in the Administrative boundaries component. The value for Country boundaries width is determined by selecting a point along a slider. This component property affects the width of features from several layers including
Unlike layer properties, component properties are not directly related to the Mapbox Style Specification and cannot be edited outside Mapbox Studio (at runtime).
In map styles built using components, color- and typography-related options for features across components are determined by the properties defined in the Color and Typography tabs at the bottom of the Components panel. Read more in the reference section on Colors and Typography.
A layer property is one of many available options for styling a single layer. Layer properties often offer more fine-grained control than component properties. Width for line layers is an example of a layer property. The value for the width property is a number representing pixels.
Layer properties directly align with paint and layout properties outlined in the Mapbox Style Specification. Custom layers are styled solely using layer properties while layers within components can be styled using a combination of component properties and layer property overrides (detailed below).
Each template style comes with a predefined set of components, but you can add or remove components to customize your map. For example, you can add the Satellite imagery component to the Monochrome template style and turn on the Fade in on zoom component property to display satellite imagery at high zoom levels. You can also remove any component from the map style.
It is not possible to build custom components. It is also not possible to add or remove individual layers from an existing component.
There are two options for customizing layer properties in a layer that is styled using component properties. You can either override the value of a layer property set by a component property or eject the component.
When you override the value of a layer property, the override affects only one layer property for one layer. Manual overrides can be reverted at any time.
Overrides are appropriate for customizing a few layer properties in a few different layers.
When you eject a component, you are no longer able to edit the layers within that component as a single unit. For example, ejecting the Road network component in the Mapbox Streets style would result in over 50 layers that need to be styled individually using layer properties.
After ejecting a component, the layers will continue to use the layer properties inherited from the initial component properties until they are manually edited. Going forward all layers must be edited using layer properties directly. Once a component is ejected, it can't be reversed.
Ejecting a component might be appropriate when you want to change many layer properties across many layers in the same component. It is also necessary when you want to reorder layers within a component or put a custom layer between layers within a single component.
The style JSON that results from making a map with components will adhere to the Mapbox Style Specification and can be used like any other Mapbox map style in Mapbox GL JS, our mobile Maps SDKs for iOS and Android, and with our Static Images API.
You can interact with, add, and remove individual layers and change layer properties at runtime when using Mapbox GL JS or our mobile Maps SDKs. It is not possible to change component properties at runtime. Component properties can only be edited in the Mapbox Studio style editor.