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 faster.

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. The Images option in the debug panel displays the amount of pixels used in the sprite.

image of spritesheet usage in debug panel

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 can have a maximum size of 1024x1024 pixels (2048x2048 for high DPI displays) – that means the whole sprite containing all icons must be smaller than 1024x1024 pixels. 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, check out the Mapbox Style Reference: Sprites.