Skip to main content

sprite

Additional Developer Resources

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:

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.

Related resources:

Additional Developer Resources
Was this page helpful?