> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ja/style-spec/llms.txt)

# Sprite

A [**sprite**](https://docs.mapbox.com/help/glossary/sprite/) is a single image that contains all the icon and pattern images included in a [style](https://docs.mapbox.com/help/glossary/style/).

When a sprite is associated with a style, its images can be used to render the following style properties: [`background-pattern`](https://docs.mapbox.com/ja/style-spec/reference/layers#paint-background-background-pattern), [`fill-pattern`](https://docs.mapbox.com/ja/style-spec/reference/layers#paint-fill-fill-pattern), [`line-pattern`](https://docs.mapbox.com/ja/style-spec/reference/layers#paint-line-line-pattern), [`fill-extrusion-pattern`](https://docs.mapbox.com/ja/style-spec/reference/layers#paint-fill-extrusion-fill-extrusion-pattern) and [`icon-image`](https://docs.mapbox.com/ja/style-spec/reference/layers#layout-symbol-icon-image).

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

```json
"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](https://docs.mapbox.com/ja/style-spec/reference/sprite#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`](https://datacadamia.com/web/css/pixel_ratio)) 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:

```json
{
    "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`](https://docs.mapbox.com/ja/style-spec/reference/layers#layout-symbol-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:

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

![Illustration showing how optional properties are applied to an example highway shield image.](https://docs.mapbox.com/ja/assets/ideal-img/sprite-optional-properties.480.png)

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](https://www.khronos.org/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](https://docs.mapbox.com/help/glossary/sprite/).

### Creating sprite files

You can create sprite files in two ways:

-   You can create a Mapbox-hosted style using [Mapbox Studio](https://docs.mapbox.com/help/glossary/mapbox-studio/) or the [Styles API](https://docs.mapbox.com/api/maps/styles/#create-a-style), 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](https://docs.mapbox.com/api/maps/styles/#add-new-image-to-sprite) or [batch image](https://docs.mapbox.com/api/maps/styles/#add-multiple-new-images-to-sprite) 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](https://github.com/mapbox/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`.