A sprite is a single image that contains all the icons included in a style. By combining a lot of small images into a single image (the sprite), you can reduce the number of requests needed to fetch all the images, which improves performance and makes your map load more quickly.

When you upload SVG icons to Mapbox Studio, it will be added to your style's sprite automatically. Similarly, all Mapbox template styles come with their own sprites, filled with icons that you can use with the given style.

A sprite combines many icons into a single image:

streets sprite example

Every sprite has a complimentary JSON file that defines each icon in the sprite, including the icon's size and position within the sprite:

"airport-15": {
  "width": 42,
  "height": 42,
  "x": 76,
  "y": 300,
  "pixelRatio": 2,
  "visible": true

This means that you can reference a specific icon in a sprite by name, such as airport-15, and the map renderer will reference the JSON file to get data about the icon, then only show that specific icon within the larger sprite.

You can retrieve a sprite as a JSON document or a PNG file using the Mapbox Styles API endpoint, but we strongly recommend that you not build in a way that relies on any given icon or icon name within the sprite, since the images in a style’s sprite can change depending on which style components are active.

How to view all images in a sprite

Learn how to retrieve a sprite as a JSON document or a PNG file using the Mapbox Styles API.

Related resources:

Was this page helpful?