Skip to main content

Styles

The Mapbox Studio style editor is a tool for creating map styles. A style is a set of rules for how your map will be rendered on a page. It includes references to your data, map images (icons, markers, patterns), fonts, and, most importantly, it defines how all your data should be styled on your map.

Mapbox Studio topics covered in this section:

with the dataset editor

Upload

with the dataset editor

Dataset

by exporting your dataset

Tileset

on the styles page

Template style

in the style editor

Custom style

containing your tileset in the style editor

Add data to style

in the style editor

Style data

in the style editor

Publish

What is a style?

A style is a JSON document that conforms to the Mapbox Style Specification. The style specification is designed especially for Mapbox GL JS (browser) and the Mapbox mobile SDKs (mobile) to read and understand so your map can be rendered on the page. The style controls almost everything about the map.

Style editor

The Mapbox Studio style editor allows you to create a custom style by editing components, adding layers, uploading custom icons, and publishing your style.

To open the style editor, click on the name of any style listed on your Styles page and it will open in the style editor.

Styling panel for editing components and layers

Toolbar

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Map canvas

Use the Layers panel on the left side of the style editor to edit the appearance of map features. For styles that use components, and editing interface appears to style many layers at once.

All changes made to your style will appear on the map canvas in the center of the style editor. You can click on the map to see all layers at a single point and when the Select data panel is open, you can inspect individual features from the selected tileset to view their properties. Read more about how the map canvas works below.

Use the toolbar along the top of the screen to adjust style settings, manage icons and fonts, export an image to print, and publish your style.

Publish

The Publish button in the upper right of the style editor allows you to save your style so you can use it in production applications.

Every change you make is tracked within Mapbox Studio, and saved as a draft version of your style. The changes will not show in any of your production applications until you click Publish. Updates can take up to 15 minutes to show on your live map.

For more information on draft vs. production styles, see Publish your style.

Components

alert
Try Mapbox Standard

We're phasing out components in favor of configuration options that was introduced with GLJS v3 and Maps SDK v11. Configuration options can be declared by styles to customize its appearance and is used in the Mapbox Standard style to toggle the visibility of specific labels, adjust the lighting, or change the font. Read more about configuration options here and learn more about the Standard style here.

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.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Components list

All components in the current style are under the layers list. While there are over a dozen components used throughout Mapbox template styles, the exact list of components will depend on the template style you are editing.

Managing components

There are several options for managing components at the top of the list, including:

  • plus Add new layer: Click + to and choose a new component for your style.
  • noeye / eye Hide/show: Select the component in the list and click the noeye icon to hide all features from the map. To show, click the eye icon.
  • trash Delete layer or component: Select the component in the list and click the trash icon to permanently remove it.
  • Eject component: Select a component in the list and right-click to see a context menu with the option to eject. When you eject a component, you are no longer able to edit the layers within that component as a single unit. After ejecting a component, the layers will continue to use the layer properties inherited from the initial component properties until they are manually edited. After the component is ejected, all the layers must be styled using layer properties directly. Once a component is ejected, it can't be reversed.

Edit component properties

To edit the style of map features in a component, click on the name of the component in the list. A panel listing the available component properties will open.

There are a few component properties for each component, and the properties available vary between components. 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.

book
Component properties and the Mapbox Style Specification

Unlike layer properties, component properties are not directly related to the Mapbox Style Specification and cannot be edited outside Mapbox Studio (at runtime).

Colors

The global Colors section displays colors used throughout the style. There are many component color properties you can define in Mapbox template styles. A component color property applies a single color to many features across components. Greenspace is an example of a component color property that applies to features in three different components (Point of interest labels, Walking, cycling, etc. and Land & water).

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

The color palette contains a list of possible component color properties. You can add and remove color properties in the color palette. After a color property is added to your palette, you can click on that list item to change its value. You can then select a new color on the color picker or define an RGBA, HSLA, or hex code.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Not every component color property has to be included in the color palette. If a component color property is not included in the color palette (no color is assigned), it will fall back to the color defined for the Base component color property, which can’t be removed. This means you will always have a well-coordinated palette without needing to choose a value for every possible component color property.

For example, if the color assigned to Base is purple and Greenspace is green, green parks will be on top of a purple base. If you remove Greenspace from the palette, your parks will turn a purple shade.

This is a pattern we use in our template styles. For example, the default color palette for Streets has 13 colors while Monochrome's default color palette has only 1 color.

Typography

The Typography section displays fonts and text styles used throughout your style. There are up to eight component typography properties you can define in Mapbox template styles. A component typography property applies font and text styles to features in one or more components. Minor cities is an example of a typography property that applies to a subset of features in the Place labels component.

You can define the font, set the text size, and transform the case (uppercase, lowercase) by clicking the item in the list to open a typography panel.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Ejecting

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.

book
Reordering layer groups in a Data visualization component

You can reorder layer groups belonging to a data visualization component without ejecting the component.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Updating

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.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

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

The Mapbox Studio style editor is a tool for creating map styles. A style is a set of rules for how your map will be rendered on a page. It includes references to your data, map images (icons, markers, patterns), fonts, and, most importantly, it defines how all your data should be styled on your map.

Mapbox Studio topics covered in this section:

with the dataset editor

Upload

with the dataset editor

Dataset

by exporting your dataset

Tileset

on the styles page

Template style

in the style editor

Custom style

containing your tileset in the style editor

Add data to style

in the style editor

Style data

in the style editor

Publish

What is a style?

A style is a JSON document that conforms to the Mapbox Style Specification. The style specification is designed especially for Mapbox GL JS (browser) and the Mapbox mobile SDKs (mobile) to read and understand so your map can be rendered on the page. The style controls almost everything about the map.

Style editor

The Mapbox Studio style editor allows you to create a custom style by editing components, adding layers, uploading custom icons, and publishing your style.

To open the style editor, click on the name of any style listed on your Styles page and it will open in the style editor.

Styling panel for editing components and layers

Toolbar

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Map canvas

Use the Layers panel on the left side of the style editor to edit the appearance of map features. For styles that use components, and editing interface appears to style many layers at once.

All changes made to your style will appear on the map canvas in the center of the style editor. You can click on the map to see all layers at a single point and when the Select data panel is open, you can inspect individual features from the selected tileset to view their properties. Read more about how the map canvas works below.

Use the toolbar along the top of the screen to adjust style settings, manage icons and fonts, export an image to print, and publish your style.

Publish

The Publish button in the upper right of the style editor allows you to save your style so you can use it in production applications.

Every change you make is tracked within Mapbox Studio, and saved as a draft version of your style. The changes will not show in any of your production applications until you click Publish. Updates can take up to 15 minutes to show on your live map.

For more information on draft vs. production styles, see Publish your style.

Layers

A layer is a styled representation of data of a single type (for example fill, line, or symbol). Layers can be a part of a component, but don’t have to be.

Layers power your map's visualization. Without layers, you cannot see your data. You can create multiple layers from the same data and you can filter data by attributes for styling in a layer. You can also fill the canvas with a color or pattern which will apply across the whole world.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

You can always access the Layers list by clicking the Layers tab in the upper left of the style editor. There are several options for managing layers at the top of the list, including:

  • plus Add new layer and choose "Custom layer…".
  • duplicate Duplicate a layer to create a copy of an existing layer.
  • folder Group or Ungroup layers to style them individually.
  • noeye eye Hide and Show layers.
  • trash Delete layer to permanently remove a layer. You can undo this using CTRL + Z in the current session, but this cannot be undone after you close your style.
  • menu Reorder layers by clicking and dragging the menu next to each layer list item.

Add layer

There are a few options when you add a custom layer to your style: Source, Upload data, and Add tileset by ID.

These options allow you to add a layer that contains specific shapes (polygons, lines, or points) that cover part of the map. A layer from data comes from custom data that you have added to your Mapbox account. See the Geospatial data section for more information on adding custom data.

book
Source limit

There is a limit of 15 unique sources permitted in styles saved in your Mapbox account. This count includes Mapbox tilesets like Streets or Terrain. If you reach the 15 source limit, you will see an error, Failed to update style. This limit is related to sources, not layers. To reduce the number of sources needed, consider combining data before uploading and using filters in the style editor to create different layers from the same source. For more information on source limits see our Source limits in Mapbox Studio styles troubleshooting guide.

Source

The Source menu is the default option for adding a new layer to your map. Each layer needs data to work with, otherwise the style rules would not be applied to anything. To specify data for the layer, choose a source from the list of available tilesets used in your map style (Active sources), as well as a list of tilesets that are in your account but not used in the current style (Unused sources). You can use the search box to find a tileset.

Vector sources: If you select a vector source, you'll have the following options:

  • Type: allows you to select the type of layer to create either fill, fill extrusion, line, circle, symbol, heatmap, or raster data types.
  • Filter: allows you to limit features that are displayed in a layer based on data properties or geometry type.
  • Zoom extent: sets the min (start) zoom and max (last) zoom to which you data is viewed on the map (learn more about manually adjusting zoom extents).

On the canvas, you will see a preview of your data. You can click to select and view the data on the map. Hover over the data to see what data subset is below and click the Select button to populate that data into the layer you are creating.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Raster sources: If you select a raster source, your layer will automatically be assigned the Raster type. The Zoom extent option will also be available to set the min (start) zoom and max (last) zoom to which you data is viewed on the map.

RBG-encoded DEM sources: If you select an RBG-encoded DEM source, your layer will automatically be assigned the Hillshade type. The Zoom extent option will also be available to set the min (start) zoom and max (last) zoom to which you data is viewed on the map.

Upload data

Upload a new tileset to use as a layer with the harddrive Upload data option.

Use the Upload file option in the upload menu to upload a MBTiles, KML, GPX, GeoJSON, Shapefile (zipped), or CSV file to convert it into vector tiles. To create raster tiles, you can upload a GeoTIFF file.

Using the Create from dataset option in the upload menu, you can select a dataset associated with your account and convert it into a tileset.

Add tileset by ID

Add a tileset to your style using its unique tileset ID. Choose the plus Add tileset by ID option, then enter the tileset ID in the format username.identifier. To find the tileset ID for a specific tileset, go to your tilesets page. Click the options menu to the right of a tileset's name to find its tileset ID.

Background & sky layers

The background and sky layers are the only layer types without an associated source tileset.

Click plus Add new layer and choose "Background layer" which adds a layer with a fill that covers the whole world. Read more about background layers in the 'Style a layer' section below

Click plus Add new layer and choose "Sky layer" which adds a layer with a fill that covers the sky above your map's horizon line. Read more about sky layers in the 'Style a layer' section below.

Filter layers

Click filter Filter layers to show and hide layers in the layer list. You can filter by layer name by typing in the search bar or you can filter by value, layer type, or vector type.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu
  • Filter by value options include Colors, Images and patterns, Fonts, Text fields, Text options, Icon options, Symbol placement, Line widths, Line options, and Fill options.
  • Filter by layer type options include fill, line, symbol, circle, fill-extrusion, and background.
  • Filter by vector layers options include all source layers.

Style a layer

Each layer can be styled individually by clicking on the name of the layer in the Layer list. There are several layer types to choose from, which are listed below. Each layer type has a unique set of layer properties that can be specified. There are a few options for specifying property values. You can pick values individually, based on a data attribute, based on the zoom level, or the value of another property.

Override

If a layer is controlled by a component, you can override the layer styling directly by modifying its styling properties. When you override a property, it will only affect one layer property for that specific layer. Other layers controlled by the component will not be affected.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Styling layer types

fill Fill layer

A fill layer is a style layer that displays data as filled shapes. Fill layers are typically used for setting the style of the insides of polygon features, but any feature type (polygon, linestring or point) can be styled with a fill layer.

For an example of fill layer styling, see the Make a choropleth map tutorial.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

To add a pattern to a fill layer in the Mapbox Studio style editor:

  1. Click Images in the top toolbar.
  2. Click Upload SVG image.
  3. Select the desired fill layer from the layers panel on the left side of the style editor.
  4. Click the Pattern field.
  5. Click to select the desired image.

extrusion Fill-extrusion layer

Fill extrusion layers can be applied to sources containing polygon features to create 3D polygons. You can use a fill extrusion layer to add a 3D building layer in your style using the building source layer in the Mapbox Streets tileset.

Switch to the 3D tab and select "Light" to control the color, direction, and intensity of the lighting source on fill extrusion layers.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

line Line layer

You can style line layers to various widths, colors, and patterns. There are also advanced options for dash arrays and blur effects. For the most part, line layers are heavily styled and transitioned between zooms. You can also duplicate layers and filter your data for more styling control. Take a look at the map style templates Mapbox Streets or Mapbox Outdoors for examples of detailed line styling with the roads, tunnels, and bridges data layers.

To add a pattern to a line layer in the Mapbox Studio style editor:

  1. Click Images in the top toolbar.
  2. Click Upload SVG image.
  3. Select the desired line layer from the layers panel on the left side of the style editor.
  4. Click the Pattern field.
  5. Click to select the desired image.

You can also select a previously-uploaded image from this panel.

circle Circle layer

A circle layer is a style layer that displays data as circles. You can use circle layers to represent scaled or interactive data, and you can use them with data that is mostly point features. In the styling panel for the layer, click the input box for each property to change its value. Hover over a property name in the panel to see its definition.

Style by filter

Circle data can show varying data values. You can make separate circle layers, filter by an attribute in your data, and style each based on the data attribute.

For example, to style earthquake data by magnitude, you can:

  • Create three layers each using earthquakes as the data source.
  • Filter the data based on magnitude (small, medium, large).
  • Define different style properties for each one, styling higher-magnitude earthquakes as larger, darker circles.

This data can also be re-styled on-the-fly in your map with Mapbox GL JS based on user interaction or attributes in the data.

transform-uppercase Symbol layer

Symbol layers are the most complex style type in Mapbox Studio. The symbol layer type offers detailed typographic styling options for your labels and map data. Symbol layer styling is separated into four main groups: Text, Icon, Position, and Placement.

Text

Control the typography contained on your layer in the Text section.

Fonts: You can only set fonts on symbol layer types. Custom fonts can be uploaded using the Fonts toolbar item on the left of the style editor. Set fonts from the Style tab of each symbol layer, under Text, in the Font input field. Each list of unique font pairings between primary and fallback font(s) will create a new fontstack.

A fontstack is an ordered list consisting of a primary font and optional fallback font(s). An example fontstack:

"Open Sans Regular", "Arial Unicode MS Regular"

When your primary font has missing glyphs, the text will be rendered in the fallback font instead. The default fallback font set by Mapbox Studio is Arial Unicode MS Regular. Unicode fonts include more glyphs than conventional fonts, allowing for better multilingual coverage.

Language: When building a map from a Mapbox template style, map labels will appear in English by default. You can change the language of your map's labels directly in the Mapbox Studio style editor. All Mapbox template maps use the Mapbox Streets vector tileset for map features. For a list of languages available, see the Mapbox Streets vector tile reference.

How to change languages:

  1. Create a new style or edit an existing one in Mapbox Studio.
  2. Select the layer that contains the labels you'd like to edit.
  3. Under the Text tab, click the current value in the Text field. A panel will appear with all language options for the layer.
  4. Click the desired language; the map will update on select.
book
Right-to-left language support

Mapbox Studio loads the mapbox-gl-rtl-text plugin by default. This plugin adds support for text in the Arabic and Hebrew languages, which are displayed right-to-left.

Icon

Define Maki icons that are available within Mapbox Studio or add your own custom icons in the Icon styling section. To add an image to a symbol layer in the Mapbox Studio style editor:

  1. Click Images in the top toolbar.
  2. Click Upload SVG image.
  3. Select the desired symbol layer from the layers panel on the left side of the style editor.
  4. From the Style tab select the Icon tab.
  5. Click the Image field.
  6. Click to select the desired image.
Position

Position styling allows you to choose alignment, rotation, and offset for your icons and text.

Placement

Placement styling controls placement of symbols, how symbols rotate on a map, and collision behavior for text and icon symbols among each other.

flame Heatmap layer

A heatmap is a data visualization in which a range of colors represent the density of points in a particular area. Adding a source layer as a heatmap layer allows you to represent the layer's features in terms of their proximity to one another. Heatmap layers in Mapbox Studio have several configurable properties that allow you to customize your heatmap:

  • color: Defines the heatmap’s color gradient, from a minimum value to a maximum value. You can adjust the density and color of each stop individually, as well as add and delete stops. For inspiration on color choices for your heatmap, try Color Brewer.

  • opacity: Controls the global opacity of the heatmap layer.

  • radius: Sets the radius for each point in pixels. As the radius number increases, the heatmap will get smoother and have less detail.

  • weight: Measures how much each individual point contributes to the appearance of your heatmap. Heatmap layers have a weight of one by default, which means that all points are weighted equally. Increasing the weight property to five has the same effect as placing five points in the same location. You can use the Style across data range and Style with data conditions options to set the weight of your points based on specified properties.

  • intensity: A multiplier on top of the weight property. Intensity is primarily used as a convenient way to adjust the appearance of the heatmap based on zoom level.

    circlecirclecircle
    arrow-leftarrow-rightrotate
    heartmapboxmenu

raster Raster layer

Raster layers are created from GeoTIFF sources. GeoTIFFs are georeferenced images, and the available style properties include options you may associate with editing images, like opacity, saturation, contrast, and brightness.

mountain Hillshade layer

Under the available sources when you create a new layer there’s a new raster-dem source: Mapbox Terrain-DEM. When selected, it uses the hillshade layer type to provide many properties to style it.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

globe Background layer

Background layers cover the full extent of your map canvas but stop at the horizon. You can create as many background layers as you want. To create textures for your map style, use multiple background layers.

Style options for background layers include:

As patterns are created from tiled images, you can upload a custom SVG image to create a pattern effect in your map. To add SVG images:

  1. Click Images in the top toolbar.
  2. Click Upload SVG image.

The image will then be uploaded to your style and available for use on any layer.

horizon Sky layer

Sky layers cover the sky above your map's horizon line. The horizon line will be visible when your map is pitched above around 70°. Sky layers may be placed anywhere in your style's layer order and will not interfere with other types of style layers, but multiple sky layers do stack on top of each other.

Layer properties

The available properties for each layer vary by layer type. You can learn about the available properties for each layer type in the style editor by clicking caret-rightDetails.

Follow the links in the sections below to read more about the properties available for each layer type in more detail in the Mapbox Style Specification.

Value options

You can specify the values for each available property individually for each layer using the Style panel. You can also quickly match the values to the values in other layers using Apply existing value, set a value that changes based on zoom level, a data range, or data conditions, or create and use a custom formula to style a layer.

Read more about how to use each of these options for specifying property values below.

Set value

Click on each property to edit the value directly.

Style across zoom range

You can choose style properties based on zoom level by choosing Style across zoom range. Values can be specified for any number of stops at any specified zoom level.

This is useful where contrast at high zoom levels requires different colors to have the same effect at lower zoom levels or to slowly fade in features that appear at higher zoom levels. Here's an example from our Create a custom style tutorial:

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu
Rate of change

There are several different options for the rate of change:

Linear: By default, the rate of change is linear, meaning a difference of one zoom level increment will increase or decrease a value by the same amount.

Exponential: A linear rate of change can be logical for many properties, but since objects in perspective increase in size exponentially as they get closer, the exponential option allows ramps to have a different base, meaning that you can customize the curve of how much a zoom level increase affects a property change over time. For example, you might visualize the population of counties in a state by proportionally scaling the layer's Color property from yellow to red for populations between 0 and 10 million people.

Cubic Bézier: The cubic-bezier option interpolates using the cubic Bézier defined by the given control points. This can be used to create non-linear, non-exponential effects like the to CSS transition properties ease-in and ease-in-out.

Step: The step option produces discrete, stepped results by evaluating a piecewise-constant function defined by stops. This option is helpful if you want complete control over the property values used in defined intervals rather than interpolating values between stops. For example, you might visualize the population of counties in a state by assigning the color yellow to counties with less than 500,000 people, orange for 500,000-1,000,000 people, and red for counties with more than 1,000,000 people.

Here's an example of interpolating from data with a stepped rate of change from the Make a choropleth map with Mapbox tutorial:

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Style across data range

Style properties can be applied based on the value of a tileset field by choosing Style across data range. To use Style across data range, you must have a numeric data field for which you can create stops. This option is not available for every style property. For example, you can interpolate from data for the color of fill layers, but not for patterns.

Style with data conditions

Add conditional logic to your styles with Style with data conditions. Apply a style property to all features in a layer with a given data field value. The value in this field can be a string, number, or boolean. You can also use multiple values in each conditional statement.

For example, in the Mapbox Streets style, landuse types are styled by class. If class is equal to park or pitch, the feature's fill color is green. If the class of a feature is equal to hospital, the feature's fill color is pink. Another condition is applied if the class is equal to school, and there is a fallback value for any feature whose class field does not match any of the conditions (or does not exist at all).

Use a formula

The formula editor includes a full library of expressions with inline documentation for each expression. Use the formula editor for any expression that varies from the patterns used in the Style across zoom range, Style across data range, or Style with data conditions options, including any expression that uses math.

Below is an example of a formula that converts units in Mapbox Terrain’s contour layer from meters to feet.

Reset value to default

Remove any data or zoom-based styling by clicking Reset value to default.

Apply existing value

Use Apply existing value to edit the value to match an existing value. Scroll through other layer properties to match the current layer to other layers in the style.

Edit property as JSON

The Mapbox Studio style editor allows you to edit a style property's JSON directly. The style property JSON editor will facilitate workflows for advanced users and early adopters who want to use features not yet supported by the graphical interface, such as identity functions.

book
NOTE

The JSON editor can be toggled for any type of value. It will be open and cannot be closed if you have entered a value that can only be edited in the JSON editor.

Select data

There is a Select data panel for each layer. You can find it by clicking on the layer in the Layer list and then clicking the Select data tab. There are several options available to change the underlying data source.

book
Layer from data

These are the same options that are available when adding a new layer from data to your style.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Read more about the available fields in the Select data panel below.

Source

This shows the tileset source that is used in the layer. Click on the name of the tileset to change the source to another tileset from your Mapbox account. The source can be either a vector tileset or a raster tileset. The remaining properties available on the Select data panel will vary based on whether the source tileset is a vector or raster source.

Type

For layers with vector sources, the available source types are:

  • fill Fill

  • extrusion Fill-extrusion

  • circle Circle

  • line Line

  • transform-uppercase Symbol

  • flame Heatmap

Some tilesets have a combination of points, linestrings, and polygons. Use filtering by geometry type (see Filter section below) to have your layer style rules apply to only features of the selected geometry types.

For layers with raster sources, the only source type is raster Raster.

Filter

The filter option allows you to limit the features that are displayed in a layer based on a data property or geometry type.

When you filter by data field, you're styling the layer based on a smaller segment of the tileset based on its attributes. This can be useful to highlight specific features in a tileset, or you can use it to classify data into sequential groups using multiple layers.

To filter data based on field value:

  1. Click + Create filter to bring up a list of data fields in your tileset (including geometry-type).
  2. Select the data field you would like to filter by.
  3. After the new Data field is added to your filter list, use the dropdown to specify how you would like to construct the filter. Options include is, is not, ** > ** (greater than), ** < ** (less than), ** >= ** (greater than or equal to), and ** <= ** (less than or equal to).
  4. Click inside the box to define the value to apply to the filter. If you are using Mapbox data, a drop-down menu of potential values appears. If you are using custom data, you have to type in the value.
  5. Click + Add another condition to add an additional filters.

Zoom extents

Set a minimum and maximum zoom. This will only work if tilesets exist at a specific zoom levels. For more information on adjusting the zoom extent of a tileset, read our troubleshooting guide.

Manage styles

From the Styles page you can create, manage, and edit any of your styles and find links for developing with Mapbox template styles. If there are more than 25 styles in your account, the style you would like to edit may not be visible when you first load your styles page. You may need to use the search bar or navigate to the next page of styles to find your style.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

New style

From the styles page, you can create a new style to be edited in the style editor. Click New style to choose a template style. For more details on available options see Map styles.

book
NOTE

If you have previously downloaded a Mapbox Studio style, you can upload it to the Mapbox Studio style editor by unzipping your compressed style and then uploading the style.json file. All sprites, fonts, and other assets relating to your style will be referenced when your style uploads successfully.There is a limit of 15 unique sources permitted in styles saved in your Mapbox account. This count includes Mapbox tilesets like Streets or Terrain. If you reach the 15 source limit, you will see an error, Failed to update style. This limit is related to sources, not layers. To reduce the number of sources needed, consider combining data before uploading and using filters in the style editor to create different layers from the same source. For more information on source limits, see our Source limits in Mapbox Studio styles troubleshooting guide.

Search styles

Use the Search styles search bar to filter or reorder your list of styles so they are easier to find and manage.

  • Search styles: You can search for styles by name or style ID.
  • Sort styles: You can sort styles by name or date modified.

Click on the options menu next to each style to uncover options for altering and using that style. Read more about what each menu item does below.

globe Details

Click globe Details to see a preview of this style and see options for editing and managing this style.

duplicate Duplicate

Create a new style with the same layers and data as the existing style. The new copy will have a unique style ID.

harddrive Replace

Upload a new style and replace the existing version. The file you upload must be a JSON document adhering to the Mapbox Style Specification that references an available sprite containing all icons and images used in the style and all fonts used in the style. You cannot replace a style with one that does not reference an available sprite or font stack.

lock Make public or private

Choose whether a style should be private or public. If a style is public, the style URL can be used by any Mapbox user with their access token. But, only the owner of a style can make changes or delete a style, even if it's public. If a style is private, the style URL can only be used with an access token from the owner's account. By default, new styles created in Mapbox Studio are private.

trash Delete

You can permanently delete a style from your account at any time. Deleted styles may not be recovered.

undo Revert to last publish

Roll back changes to the last time you hit the Publish button in the style editor. This cannot be undone. You will lose any changes made between the current publish and the last publish.

Style URL

Any time you create a style with Mapbox Studio it generates a style URL. The style URL allows you to reference that specific style with the Mapbox GL JS API or native SDKs.

Map canvas

All changes made to your style will appear on the map in the center of the style editor. You can interact with the map to see all layers at a single point and when the Select data panel is open, you can inspect individual features from the selected tileset to view their properties.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

search Search places

search magnifying glass icon allows you to search for locations on the map. Type in what you're looking for and select the result and search will take you to the exact location. This search is powered by the Mapbox Geocoding API.

Although you can search and view places in the style editor, you cannot create new points in the style editor. See the next section on the Mapbox Studio dataset editor to learn how to search for places and create new features to be added to your map.

Toolbar

The toolbar is always along the top of the screen in Mapbox Studio style editor.

Share and Publish

For more information on sharing and publishing your style, see Publish your style.

book
Attribution for printed maps

Read the Mapbox print policy before printing any Mapbox maps. Print maps require appropriate Mapbox attribution.

Click printer Print to toggle the print panel on and off. Position your map and specify Print export settings in the print panel. Settings include image dimensions (in inches or centimeters), resolution (in PPI), and file format (PNG or JPG). The maximum image export is 8,000 px by 8,000 px. Use the Preview section to make sure that the print shows your desired image. When you have adjusted the size, resolution, and format to your liking, click the Export button.

Mapbox Studio offers 100 free high resolution image exports per account to all users. Your use of the Mapbox Studio print export option will not be reflected on your invoice. After 100 exports have been used on your account, you will no longer be able to access the print panel. If you need more than 100 prints, you can purchase an annual license that allows for a higher number of image exports and prints. Contact Mapbox sales for more information.

If you do not want to purchase an annual license that provides more than 100 high resolution image exports, you can use the Mapbox Static Images API playground. With the Mapbox Static Images API, image exports can be up to 1,280 px by 1,280 px in size. While enabling retina may improve the quality of the image, you cannot export at a higher resolution using the Static Images API.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Settings

The Settings menu includes a lot of options including:

Debug tools

Debug tools help to visualize behavior that is otherwise invisible to the rendered style. They have no effect on the published style.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu
  • Satellite imagery compares your style against satellite imagery. This is useful for checking the accuracy of map features.
  • Raster tiles views raster tiles of your style. Note that style updates may be delayed in the raster tiles.
  • Tile boundaries renders outlines to show tile boundaries. Occasionally features will be affected by crossing tile boundaries. Toggling visibility of tile boundaries is useful for debugging clipped or missing symbols.
  • Collision boxes renders collision boxes for symbols. This is also useful for debugging clipped or missing symbols.
  • Overdraw inspector displays how many times each pixel is being shaded. This is useful for optimizing hardware where pixel processing presents a bottleneck.
  • Color blindness simulator lets you simulate different types of color blindness to make sure your map is legible for all viewers.
  • Language preview render your style in different languages. This is useful for simulating end-user device language settings.
  • Worldview preview render your style with a different worldview. Once published, worldview is determined by the style's Tileset specification.

Supported Mapbox SDK versions

Make sure that all features you are using are supported with specific versions of Mapbox SDKs and view warnings related to compatibility.

Default map position

Set the zoom, bearing (rotation), pitch, and latitude and longitude coordinates for the current map view. You can also toggle Lock default position so that the map returns to the current position whenever the style is opened.

Compare styles

Compare your working style with another style from your account. Select the style to compare, then click Compare to open a dialog box. Use the swipe arrows to compare maps. Hit Escape or click away from the Compare tool to dismiss the window.

Layer overview

The Layer overview section shows a list of tilesets used in style layers that rely on the tileset. Tilesets are sources. Sources include vector or raster data files uploaded to your account. Your account also includes access to Mapbox tilesets.

There is a limit of 15 unique sources permitted in styles made with the style editor. You can check the number of sources used in Settings Layer overview popover.

Source compositing does not reduce the number of sources counted toward this limit. For example, if you are using a template style that references both the Mapbox Streets and Terrain tilesets (in other words, two tileset sources) and you add one custom tileset, even if the tilesets are bundled into one composite source, the total number of tileset sources used would be 3. In this example, you could add an additional 12 sources before hitting the 15 source limit.

For more information on source limits, see our Source limits in Mapbox Studio styles troubleshooting guide.

Source compositing

Any sources in your Mapbox Studio style are composited, or combined, by default. When source compositing is enabled, any Mapbox vector tilesets used and any custom vector tilesets added to your style in the future will be bundled into one composite source. Compositing improves label placement calculations across tilesets and makes maps load faster.

Source composting can be turned on or off in the Settings section of the toolbar. When source compositing is turned off, you cannot make label placement calculations between layers from different sources.

book
Adding layers after turning source compositing off

When you turn source compositing off, this only prevents new sources that you add to the style after clicking the toggle button from being composited. While sources that you add after turning compositing off are added as distinct sources, the existing sources in your style are still composited.If you want a style with no source compositing, you must begin with the Blank template and turn off source compositing before you add any layers.

According to the Mapbox Vector Tile Specification, no two vector layers in a vector tileset may have the same ID. If you try to composite sources with the same ID, a modal will be displayed in the style editor to walk you through resolving the name conflicts.

book
Source limit

There is a limit of 15 unique sources permitted in styles made with the style editor. Source compositing does not reduce the number of sources counted toward this limit. For example, if you are using a template style that references both the Mapbox Streets and Terrain tilesets (in other words, two tileset sources) and you add two custom tilesets, even if the tilesets are bundled into one composite source, the total number of tileset sources would be 4. In this example, you could add an additional 11 sources before hitting the 15 source limit. For more information on source limits see our Source limits in Mapbox Studio styles troubleshooting guide.

History

See a complete history of changes made in the current session (since opening the style editor). Read more on this functionality in our blog post, Visual undo & redo in Mapbox Studio.

3D properties

Access 3D styling features from the Global tab to improve sense of depth and realism.

Projection

You can specify a style's projection property, which sets the default projection a map is rendered in.

Light

You can specify the anchor, color, intensity, and position of a style's light property, which impacts the appearance of fill extrusion layers. Light attributes can also be adjusted by zoom level.

Terrain

Enable 3D terrain in any map style. After enabling terrain, adjust Exaggeration to multiply all elevation height calculations by a modifier.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Fog

Enable fog in any map style to fade out distant objects. After enabling fog, adjust Range to set the depth of the fog field, Horizon blend to control the blending between fog and sky, or Color to style the color of the fog.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Images

Add and remove images from your style's sprite in this popover. To display images on your map, select in the layer panel on the left.

Fonts

Add and view fonts associated with your Mapbox account (across all styles). Browse Mapbox fonts or upload custom TTF or OTF fonts.

Help

Open Help for links to our help page and contact page. Turn on Tips to become oriented in the style editor. See a full list map interactions and keyboard shortcuts.