Troubleshooting SVG image errors in Mapbox Studio

The Mapbox Studio style editor supports the SVG format for icons and patterns. Studio uses SVG because it’s scalable and supports devices with a range of screen resolutions. Behind the scenes, the Mapbox Styles API uses the source SVGs to render sprites (collections of PNGs) at a variety of resolutions, then delivers the proper sprite based on a user’s device. For example, if a user views your map on a device with a high resolution screen, they will receive a 2x sprite. If a user views your map on a device with a low resolution screen, they receive a 1x sprite.

Common issues

Sometimes SVGs fail to upload or upload successfully, but do not appear as expected. Here are some common issues and suggestions for troubleshooting them.

Black images with no color

If you are able to add your SVG to Mapbox Studio, but appears black, it’s likely because you are using <style> tags to assign style properties rather than using inline style attributes. Mapbox Studio does not support style properties added in <style> tags. If you are using Adobe Illustrator to create your SVG, make sure you have selected Presentation Attributes and unchecked Responsive checkbox.

Sketch icons are not rendered correctly in Mapbox Studio

The SVGs Sketch generates may include some SVG filters that can not be correctly rendered by Mapbox Studio. You can open the SVG in Adobe Illustrator and do Object > Expand Appearance.

“Icon upload failed” error

If your icon fails to upload, it’s likely either because the SVG is too large or the file is not a valid SVG. We recommend you make sure that:

  • The images you’re uploading are smaller than the sprite dimension limit: 1024px x 1024px. You can learn more about how sprites work here.
  • There are no syntax errors in your SVG file.

Size property causing icon to look blurry

If you adjust an icon’s size in the Mapbox Studio style editor or in code, you might notice that it seems fuzzy or dithered. Icons look best when the size property is set to 1. We recommend uploading larger SVGs if you want to display bigger images on the map.

Change an icon from the Mapbox template styles

You can get the original SVGs used in any Studio styles by clicking on the Download button of a style from the Mapbox Studio style list or use the Maki editor to create an entire set of custom designed icons.

Create SVG icons in Adobe Illustrator

We support a wide range of SVG features, but some features aren’t available. To make sure that your vector graphics are accurately included in your maps, follow these steps:

Make sure everything is in vector format. If you’ve applied some Illustrator effects, go to Object > Expand Appearance. Do not include symbols or raster images as part of your SVGs, whether embedded or linked.

There are two ways to generate an .svg file from Illustrator: Export and Save As.

Export

  • To Export, go to File > Export.
  • Click the Use Artboards and enter the artboard number within the Range box.
  • Click the Export button.
  • In the SVG Options window, under Advanced Options panel, select Presentation Attributes as the Styling option. Uncheck the Responsive checkbox, and make sure you have a Decimal value greater than 3. Your settings should look like this:

adobe illustrator SVG export settings

Save as

  • To Save As, go to File > Save As, and click Save As.
  • In the SVG Options window, select SVG 1.1 for SVG profiles, select Presentation Attributes for CSS Properties, select a value greater than 3 for Decimal Places, and uncheck the Responsive checkbox. Your settings should look like this:

adobe illustrator SVG export settings