Custom images in Mapbox Studio and Mapbox GL JS

Mapbox Studio supports custom SVG images as icons and patterns for fill, line, symbol, and background layers. You can also use the custom images that you upload to your Mapbox Studio style in your Mapbox GL JS code.

This guide covers how to create custom images, upload them to Mapbox Studio, locate available images for styles, and use them in Mapbox GL JS.

Create custom images

Your custom image must be in the SVG format. SVG is required to keep map styles crisp at all pixel densities: screen, retina, and print. Mapbox rasterizes SVG images to multiple sizes of PNG for final display on maps so that they’re fast and consistent across platforms.

You can find SVG icons everywhere on the web, like geomicons and icomoon, or create them yourself with Illustrator, Sketch, Inkscape, and many other desktop applications.

See our Troubleshooting: SVG asset errors in Mapbox Studio for guidelines and help when working with your SVG images.

Mapbox Studio

With the Mapbox Studio style editor, you can upload your SVG icons to use on your map. You can apply your images to symbol layers as an Image and fill, line, and background layers as a Pattern. You can also drag and drop your SVG icons to quickly add your icons to your style.

Symbol layers

Here’s how 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.

Fill, line, and background layers

Here’s how to add a pattern to a fill, line, or background 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.

Mapbox GL JS

Unlike Mapbox.js that uses Maki icons, Mapbox GL JS uses the style’s spritesheet to render images. You must upload any custom images to a style in the Mapbox Studio style editor to use the image with Mapbox GL JS.

Whether you’re using a Mapbox style or your custom style, here’s how to locate the icons names and then use them in your code.

Locate Mapbox style’s images

If you’re using a Mapbox style, you can find its collections of images that you can reference in your Mapbox GL JS code:

Continue to the next section: Use images in Mapbox GL JS.

Locate custom style’s images

To find the available images in your custom Mapbox Studio style:

  1. Open any symbol, fill, line, or background layer in your style.
  2. Click either the Image or Pattern field to open the sprite panel.
  3. Hover over the images to find the icon’s name.

Continue to the next section: Use images in Mapbox GL JS.

Use images in Mapbox GL JS

You can use the name of the image as the value for icon-image, background-pattern, fill-pattern, and line-pattern in Mapbox GL JS.

Here are resources and examples of icons in use:

Additional questions? Ask our support team or learn more about How Mapbox Works.