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 drawn on the page – it includes references to your data, map images (icons, markers, patterns), fonts, and, most importantly, it defines how all of your data should be styled on your map.

Mapbox Studio topics covered in this section:

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.

The Mapbox Styles API powers your ability to change the fonts, colors, and icons on a map style through the visual interface of Mapbox Studio. The Mapbox Styles API is an integral part of our cartography software and is used across several Mapbox tools.

The style editor

The Mapbox Studio style editor is a visual interface for creating styles. Each layer you add to the style in the Mapbox Studio style editor is added to this JSON object via the Styles API when you save and subsequently passed to the browser or device when the map is requested. Once created, you can keep your style hosted with Mapbox to serve to your map or you can download the JSON object as a document.

Cartogram

You can also use Cartogram, a new drag-and-drop tool, to create a custom map in seconds. Upload a picture, select the colors you want, and get a map that fits your brand and style, ready to be used in your website or mobile application, or edited in Mapbox Studio.

screenshot of how to save a Cartogram map and open it in the style editor in Mapbox Studio

Mapbox template styles

Mapbox Studio also provides several template styles that can be used out of the box or can serve as a base for custom styles. For more information about these styles, see the Maps page.

a preview of all template map styles

Designer maps

In addition to our template styles, we also provide several designer maps that can be edited in the Mapbox Studio style editor or used directly in your applications. Create an account to subscribe to our mailing list and receive designer maps as they are released.

Browse all designer maps and add them to your account

a preview of all designer map styles

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.

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.

New style

Click the New style button to create a new style that can be edited in the style editor. You can either Pick a template style to start with or Upload a style that conforms to the Mapbox Style Specification. Read more information about the two options below:

Pick a template

Choose one of the Mapbox template styles to open in the style editor, or start with a blank slate.

create new style

Upload a style

You can upload your own style JSON according to the Mapbox Style Specification.

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.

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

Download

Download a zip file containing all pieces of your style including a JSON document adhering to the Mapbox Style Specification, the sprite containing all icons and images used in the style, and all fonts used in the style. This can be stored locally, altered in a text editor, uploaded to your account, or shared with other Mapbox Studio users.

Duplicate

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

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.

Revert to last publish

Revert a style to the last published version. Changes made since the last publish will not be recoverable.

Generate static image

You can create a static map from your custom style or a Mapbox template style using the Mapbox Studio image export tool. For more info on this tool, see the Publish your style section of this manual this.

Share, develop, & use

You can also add your style to a web or mobile application. See the Publish your style section of this manual for more information and instructions.

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. However, 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 the owner’s account. By default, new styles created in Mapbox Studio are private.

Delete

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

Fonts page

The Fonts page in the Styles section allows you to add and manage custom fonts for use in your map styles. From your Fonts page, you can view all the font families you have uploaded to your account as well as all the Mapbox font families you have access to.

fonts page

To upload new fonts, click Upload fonts at the top of the page. Your font will now appear in the Font panel when you edit a symbol layer’s font field.

If you are using many custom fonts, see Manage your fontstacks for optimal map rendering.

Style editor

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

Layers list

Style a layer & Select data

Properties panel

Map canvas

Toolbar

Layers list

A layer is a styled representation of data or the canvas of your map. Layers power your map’s visualization – without layers, your data will not be shown. 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.

Publish

The Publish button at the top of the Layers list allows you to save your style for sharing and use in other applications. Every change you make is tracked within Mapbox Studio, but the changes will not show on any of your applications or on the share page until you click Publish. Updates can take anywhere from 5 to 10 minutes to show on your live map. For more information, see Share, develop, & use a style.

New layer

In the style editor, you can add custom data as new layers. To create a new layer, click + New layer at the top of the layers panel.

There are two options when adding a new layer to your style:

  • Layer from data: 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 Uploads section for more information on adding custom data.
  • Background layer: Add a layer that will cover the entire map canvas.

Read more about how to add a new layer from data or a background layer below:

Layer from data

Each layer needs data to work with, otherwise the style rules would not be applied to anything. (The exception is a background layer – see the next section for more details). To add data for the layer, choose the Layer from data link.

Source: Click Pick a source for this layer to see a list of tilesets used currently in your map style as well as tilesets that are in your account but not used in the current style. You can use the search box to find a tileset, or upload a new tileset with the New tileset button.

Vector sources:

  • Reset selection: to reset your tileset selection
  • Tileset details: to view launch the tileset information page which will provide information on the tileset such as the attributes and values available to filter and access
  • Type: allows you to select the type of layer to create either line, raster, symbol, fill, or circle data types
  • 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 in here)
  • Filter by geometry types: allows to show all or select geometry types in your tileset by Polygon LineString and Point
  • Field values: allows you to filter your tileset based on attributes and values contained within the tileset; you can set multiple data filters
  • Create layer: After you’ve made your selections, click Create layer and you’re done. Your layer will appear in the list right above whatever layer was previously selected; if no layer was previously selected, your new layer will appear at the top of the list.

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.

hover and click data

Raster sources:

  • Type: allows you to select the type of layer to create a raster layer
  • Zoom extent: sets the min (start) zoom and max (last) zoom to which you data is viewed on the map
  • Create layer: After you’ve made your selections, click Create layer and you’re done. Your layer will appear in the list right above whatever layer was previously selected; if no layer was previously selected, your new layer will appear at the top of the list.

Background layer

A background layer is a style layer without an associated tileset. Background layers cover the full extent of your map canvas. You can create as many background layers as you want. Using multiple background layers is a great way to create textures for your map styles.

To create a background layer, click + New layer at the top of the layers panel, choose Background layer and click the Create background layer button.

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:

  • In the layer panel, click the pattern box
  • Click Add SVG images
  • Select the image on your local machine

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

Manage layers

The Layers list is always available and visible along the left side of the style editor window. There are several tools for managing layers at the top of the list, including:

  • Duplicate a layer to create a copy of an existing layer.
  • Group and Ungroup layers to style them individually and sort them.
  • Hide and Show layers.
  • 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.
  • Reorder layers by clicking and dragging the next to each layer list item.

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, pick a value of another property, or change properties based on the zoom level.

Layer types

The different kinds of layers that you can add to your style are listed below:

  • Fill layers display data as filled shapes.
  • Fill-extrusion layers display data as three-dimensional filled shapes.
  • Circle layers displays data as circles.
  • Line layers to display data as lines.
  • Symbol layers are the most complex layer type in Mapbox Studio. The symbol layer type offers very detailed typographic styling options for your labels and map data. Symbol layer styling is separated into four main groups: Text, Icon, Position, and Placement.
  • Raster layers display georeferenced images, such as satellite imagery.
  • Background layers don’t display data, they are style layers that cover the entire map canvas.
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 hovering over a property name.

hover to see property details

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.

Fill layer properties

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, however 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.

Style options

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

  1. Select the fill, line, or background layer from the layers panel.
  2. From the Style tab, click the Pattern field and then click Add SVG images.
  3. After your image is uploaded, click to select the desired image as the pattern.

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

Fill-extrusion properties

Properties for fill-extrusion layers include:

Line layer properties

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.

Style options

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

  1. Select the fill, line, or background layer from the layers panel.
  2. From the Style tab, click the Pattern field and then click Add SVG images.
  3. After your image is uploaded, click to select the desired image as the pattern.

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

Options

Circle layer properties

A circle layer is a style layer that displays data as circles. Circle layers are good for representing scaled or interactive data, and they are best used with data that is mostly point features.

Style options

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 is perfect for showing 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.

Symbol layer properties

Symbol layers are the most complex style type in Mapbox Studio. The symbol layer type offers very 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. Symbol layer style options:

Halo options:

Fonts: Fonts can only be set on symbol layer types. 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 value next to Text field. A panel will appear with all language options for the layer.
  4. Click the desired language; the map will update on select.

Instead of changing each label layer individually, you can use the Properties panel to change all the label layer’s languages. See Properties below.

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. Select the desired symbol layer from the layers panel.
  2. From the Style tab select the Icon tab.
  3. Click the Image field and then click Add SVG images.
  4. After your image is uploaded, click to select the desired image.

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

Position

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

Text positioning:

Icon positioning:

Placement

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

Map rotation:

Collision behavior:

Raster layer properties

Styling properties for raster layers include:

Background layer properties

Properties for background layers include:

For more information on background layers, see the Background layer section above.

Options for specifying property values

You can specify the values for each available property individually for each layer using Edit, quickly match the values to the values in other layers using Pick an existing value, or set a value that changes based on zoom level or property functions.

set property

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

Edit

Click on the text field for each property to edit the value. Each property can be changed to any value using Edit. The way that the value is specified will vary based on the property.

Pick existing value

Click on the text field for each property and select Pick existing value to edit the value to match an existing value. Scroll through other layer properties to easily match the current layer to other layers.

Enable zoom function

Style properties can be chosen based on zoom level by clicking the icon next to each property. 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:

By default, ramps are linear: a difference of one zoom level increment will increase or decrease a value by the same amount. This can be logical for many properties, but since objects in perspective increase in size exponentially as they get closer, we allow 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.

Enable property function

Style properties can be applied based on the value of a tileset field by clicking the button next to a style property’s text field. Property functions are not available for every style property (e.g. property functions are available for color and opacity of fill layers, but not for patterns).

When using a property function, you can choose a field to style by in the Field drop down menu. There are three different kinds of property functions you can use.

  • exponential: Interpolate a style property between two field values. 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.
  • interval: Apply the same style property to a defined range of values. 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.
  • categorical: Apply a style property to all features which have a given field value. The value in this field can be a string or number. For example, you might visualize local restaurant locations by type of restaurant, where fast-food is yellow, fast-casual is blue, and fine-dining is green.

Here’s an example from the Make a choropleth map with Mapbox tutorial:

Select data

There is a Select data panel for each layer. It can be found 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.

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
  • Circle
  • Line
  • Symbol

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.

Zoom

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

Filter

Geometry type: To filter by geometry type, click to remove the geometries you want to be excluded. All are included by default.

Field value: When you filter by field value, 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 + Add filter to bring up a list of fields in your tileset.
  2. Select the field to filter on.
  3. Select 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 the box below the filter creation options to define the value of the field to filter on. 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 value to add an additional filter based on the field value.

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.

Properties panel

The Properties panel can be found at the bottom of the Layers list. Click Properties to expand. The properties panel allows you to style all of the properties of the same type at once. This will allow you to, for example, style all of the colors in the whole map in the same place. This is helpful for keeping colors, numbers, patterns, fonts, strings, and other options consistent.

The property types pane has two modes: By value and By property. Each can be filtered by layer type and sorted by name or layer count. The By value pane lists each different property and value separately with a list of layers underneath that use that property and value. Changing the value in the property type pane will change the value for all layers that use it. The By property panel lists all the different properties in each type and shows the values for each layer that uses the property. This is useful if you’re trying to change the font for all of your labels at once or if you want to create a palate of colors for use across multiple layers.

There are six different types of properties you can assign for layers in your style: Color, Number, Images, Font stack, Text field, and Option. A full list can be seen in the properties panel.

Read more on managing your properties in our blog post, Designing the Blueprint style in Mapbox Studio.

Toolbar

The toolbar is always in the upper right of the screen in Mapbox Studio style editor.

Full screen

Use Mapbox Studio in full screen mode.

Reset pitch

Reset pitch to zero to look at the map straight on.

Reset north

Reset the rotation of the map so north is up.

Zoom

Zoom in or out from the current map view.

Search

The Search search bar allows you to search for locations on the map. Type in what you’re looking for, and select to be taken to that 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.

Additionally, you can use the search bar to find any custom layers you have added to a style.

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. The default position that has been specified is shown below the toggle button.

Debug

Satellite imagery

Toggle Satellite imagery to compare your style to satellite imagery. This is useful for checking the accuracy of map features.

toggle satellite imagery

Tile boundaries

Toggle Tile boundaries to see tile boundaries. Occasionally features will be affected by crossing tile boundaries. Toggling visibility of tile boundaries is useful for debugging clipped or missing symbols.

tile boundaries

Collision boxes

Toggle Collision boxes to see collision boxes for symbols. This is also useful for debugging clipped or missing symbols.

collision boxes

Supported Mapbox SDK versions

Ensure that all features you are using are supported with specific versions of Mapbox SDKs.

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 Debug section of the toolbar. When source compositing is turned off, label placement calculations can not be made between layers from different sources.

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.

Compare styles

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

compare styles swipe

Reference groups

The underlying GL renderer uses reference groups to render similar layers faster. Layers with matching define properties (type, source, source layers, zoom, and filter) and style layout properties are automatically grouped. Knowing how your layers are grouped helps you optimize your style.

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.

Light

When using a fill extrusion layer, you can specify the anchor, color, and intensity of lighting. Each can also be adjusted by zoom level.

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.

Style information page

For each style, there is a style information page where you can review the sources and layers used in your style and accomplish the same tasks as you can in the menu on the Styles page.

List of sources and layers

The information page shows a list of tilesets that are used in the style and a list of 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.

The same items that exists in the menu for each style on the Styles page are listed on the right side of the style information page. See the menu section for more details.

Edit style

Click Edit to open the style editor and make changes to your style.

Next section:

Tilesets

Learn how to create and manage tilesets in Mapbox Studio.