Skip to main content

Sprite

Join the Mapbox Developers Discord Communityarrow-right

A sprite is a single image that contains all the icon and pattern images included in a style.

When a sprite is associated with a style, its images can be used to render the following style properties: background-pattern, fill-pattern, line-pattern, fill-extrusion-pattern and icon-image.

To use a sprite, a style must have a sprite property with a URL template as its value. For example:

"sprite": "mapbox://sprites/mapbox/bright-v8"

Mapbox APIs and SDKs will use this URL template to request the two sprite files required to render icons and patterns on your map. You can read more about loading sprite files below.

Sprite files​

A valid sprite source must supply two types of files: index files and image files.

Index file​

A sprite's index file is a JSON document containing a description of each image contained in the sprite. The content of this file must be a JSON object whose keys form identifiers to be used as the values of the above style properties, and whose values are objects describing the dimensions (width and height properties) and pixel ratio (pixelRatio) of each individual image and its location within the sprite (x and y).

For example, a sprite containing a single image might have the following index file contents:

{
    "poi": {
        "width": 32,
        "height": 32,
        "x": 0,
        "y": 0,
        "pixelRatio": 1
    }
}

Given this data in the sprite index file, a style could refer to the image in this sprite image by creating a symbol layer with the layout property "icon-image": "poi", or with the tokenized value "icon-image": "{icon}" and vector tile features with an icon property with the value poi.

Apart from the required properties width, height, x, y, and pixelRatio, the following optional properties are supported:

  • content: An array of four numbers, with the first two specifying the left, top corner, and the last two specifying the right, bottom corner. If present, and if the image uses icon-text-fit, the symbol's text will be resized to fit inside the content box.
  • stretchX: An array of two-element arrays, consisting of two numbers that represent the from position and the to position of areas that can be stretched.
  • stretchY: Same as stretchX, but for the vertical dimension.

For example, you could use these optional parameters to define a highway shield image with specified bounds for label text and stretchable zones that help decrease distortion when the shield is rendered on a map at a size larger than its original size in the sprite image file:

{
    "us-highway-shield": {
        ...
        "content": [14, 10, 40, 28],
        "stretchX": [[14, 22], [33, 40]],
        "stretchY": [[11, 14]]
    }
}

In the example above, the illustration shows the content area with a black dotted line (), and shows the stretchX and stretchY zones with pink () and yellow () color highlighting.

Image file​

A sprite's image file is a PNG image containing the sprite data.

The maximum size of a sprite is bounded by WebGL MAX_TEXTURE_SIZE, which depends on a client's GPU, but is usually at least 4096×4096 pixels.

You can see an example of a sprite image file on this sprite glossary entry.

Creating sprite files​

You can create sprite files in two ways:

  • You can create a Mapbox-hosted style using Mapbox Studio or the Styles API, which will automatically set your style's sprite property to the correct URL template. You can then upload custom SVG images to your style using Studio or the Styles API single image or batch image endpoints. Any Mapbox APIs that reference a Mapbox-hosted style will build and provide the sprite files automatically.

  • If you are self-hosting your style, and would like to build your own self-hosted sprite files, you can choose to do this. To build a sprite by hand, you can use spritezero-cli, a command line utility that builds Mapbox GL-compatible sprite PNG and index files from a directory of SVGs. If you are hosting your own sprite files, you will use your own URL template for the value of the sprite property in your self-hosted style.

Loading sprite files​

Mapbox APIs and SDKs will use the value of the sprite property in the style as a URL template to generate complete URLs for both sprite files:

  • First, for both index and image files, they will append @2x to the URL on high-DPI devices.
  • Second, they will append file extensions: .json for the index file, and .png for the image file.

For example, if you specified "sprite": "https://example.com/sprite" in your style, renderers would load either:

  • https://example.com/sprite.json and https://example.com/sprite.png, or
  • https://example.com/sprite@2x.json and https://example.com/sprite@2x.png.
Join the Mapbox Developers Discord Communityarrow-right
Was this page helpful?