A sprite is a single image containing all icons included in a style. Sprites are often used in web development and even video games to improve performance. By combining lots of small images into a single image (sprite), you can reduce the number of requests needed to fetch all the images, improving performance and making your map load more quickly.

If you're using Mapbox Studio, you don't have to worry about the technical underpinnings of sprites: uploading SVG icons automatically creates a sprite that your map will use. Similarly, all Mapbox template styles come with their own sprite filled with icons that you can use with that style.

If you would like to do it yourself or are interested in what's under the hood, you can also create your own sprite. Here's a rundown of all the terminology and how sprites work.

A sprite combines many icons into a single image:

streets sprite example

Sprite for Mapbox Streets

An icon is a single image found within the sprite:

airport sprite
Mapbox Streets icon named airport-15.

Sprites are limited to 500 icons. Each icon can be a maximum of 512x512 pixels and have a max file size of 400KB. Every sprite has a complimentary JSON file that defines each icon, including the icon's size and position within the sprite - kind of like directions to each icon:

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

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

To learn more about creating and editing sprites, read the Mapbox Style Reference: Sprites.

Was this page helpful?