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.

But if you’d 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:

metro sprite

Mapbox Streets icon named metro-11.

Sprites can have a maximum size of 1024x1024 pixels – 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:

  "metro-11": {
    "width": 26,
    "height": 26,
    "x": 766,
    "y": 638,
    "pixelRatio": 2
  "dot-11": {
    "width": 22,
    "height": 22,
    "x": 766,
    "y": 664,
    "pixelRatio": 2

This means that you can reference an icon by name, such as metro-11, 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.