Style components

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:

Upload

Dataset

Tileset

Template style

Custom style

Add data to style

Style data

Publish

What are components?

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, Administrative boundaries, and Data-driven circles are examples of components. Each component contains one or more 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.

You can add custom layers that use custom tileset sources to a style with a data visualization component or as individual custom layers. You can position or style such custom layers using either method.

Style a map using components

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.

Component property

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 admin-0-boundary, admin-1-boundary, admin-0-boundary-bg, and admin-1-boundary-bg.

Color and typography properties

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.

Layer property

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

Add and remove components

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.

Data visualization component

The data visualization component is a style component that you can use to create a custom data visualization in Mapbox Studio. When you add this component to any new style, Studio will prompt you to add data, choose a visualization type, and style your visualization by toggling and sliding the component controls.

Custom components

It is not possible to build custom components. It is also not possible to add or remove individual layers from an existing component.

Customize beyond components

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.

Override

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.

Eject

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.

Update components

To receive the latest features components offer, you will periodically receive updates to the components in your style. If your style has components older than the latest version available, you will see an update notification when you open Mapbox Studio. Once you view the available updates, you will see a list of changes to components and SDK compatibility since your last update. You can visually compare the current and updated versions of your style before proceeding with the update.

When ready, you have the option to update the original copy of your style or to save a copy with the updates.

Resolve conflicts

If there are any layer conflicts while updating your components, you will see a message in a popup on the lower right side of the screen that tells you what the conflicts are. Once the style has been updated, you will be able to address each conflict individually.

Once you have resolved any conflicts, your up-to-date style is ready to publish.

Use a style built with components

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.