# Sprite images (sprite_images)

Combines CSS background images into sprites. The sprite_images filter: what it does, its risks and the Apache, nginx and IIS directives.

Canonical URL: https://modpagespeed.com/docs/filters/sprite_images/

- Category: Image
- CoreFilters: No
- OptimizeForBandwidth: No
- Risk: Test first

`sprite_images` merges small CSS background images into one sprite sheet and rewrites the stylesheet so each rule shows its own region: the `background-image` URL becomes the sheet at a `.pagespeed.is.` URL, and the `background-position` shifts to the element's slice. A toolbar of icons that cost a request each then arrives in one fetch. Not a CoreFilter; enable it by name.

## How it works

Live demo: [sprite_images](https://modpagespeed.com/examples/sprite_images/).

### When it helps and when it does not

Spriting is an HTTP/1.1 technique: it exists because browsers used to open few connections per host and every icon queued. With HTTP/2 multiplexing the latency benefit is minimal, and the costs remain. Changing one icon invalidates the whole sheet, and a page that shows two icons downloads every icon packed beside them. It can still pay on icon-heavy pages with a stable icon set and a large HTTP/1.1 audience; elsewhere, measure before keeping it.

### How it decides

Only images referenced from a CSS `background` or `background-image` declaration are candidates; `<img>` tags never join a sprite. Only PNG or GIF backgrounds in rules that declare both `width` and `height` are sprited, and GIFs are converted to PNG in the sheet. The module must be able to fetch the image and learn its dimensions, and a declaration the CSS parser cannot understand is left alone rather than guessed at. Positions in the rewritten rules are computed from the packed layout: an existing `background-position` is shifted to the slice, and a rule without one gets a new `background-position` declaration.

## When to use it

- Not in CoreFilters: it runs only when you enable it by name.
- Risk rating on these docs: **Test first**.

## Risks

- Spriting increases cache invalidation scope: changing one image invalidates the entire sprite.

- Only CSS `background-image` references are sprited. Inline `<img>` tags are not affected.

- Verify with the `X-Mod-Pagespeed` response header and a `?PageSpeedFilters=-sprite_images` comparison; [Is it working?](https://modpagespeed.com/docs/is-it-working/) has the steps.

## Configuration

Enable it in the module configuration, at server, virtual-host or location scope:

**Apache**

```apache
ModPagespeedEnableFilters sprite_images
```

**nginx**

```nginx
pagespeed EnableFilters sprite_images;
```

**IIS (pagespeed.config)**

```text
pagespeed EnableFilters sprite_images
```

```css
/* before */
.icon-cart {
  background: url(/img/cart.png) no-repeat;
  width: 16px;
  height: 16px;
}
.icon-user {
  background: url(/img/user.png) no-repeat;
  width: 16px;
  height: 16px;
}

/* after: the images are stacked vertically in one sheet */
.icon-cart {
  background: url(/img/cart.png+user.png.pagespeed.is.HASH.png) no-repeat;
  width: 16px;
  height: 16px;
  background-position: 0 0;
}
.icon-user {
  background: url(/img/cart.png+user.png.pagespeed.is.HASH.png) no-repeat;
  width: 16px;
  height: 16px;
  background-position: 0 -16px;
}
```

Scoping, `ForbidFilters` and the thresholds filters read: [Choosing filters](https://modpagespeed.com/docs/filter-selection/).

## Live example

See the before and after, with the source diff: [sprite_images example](https://modpagespeed.com/examples/sprite_images/).

## Frequently asked questions

**What does the sprite_images filter do?**

`sprite_images` merges small CSS background images into one sprite sheet and rewrites the stylesheet so each rule shows its own region: the `background-image` URL becomes the sheet at a `.pagespeed.is.` URL, and the `background-position` shifts to the element's slice. A toolbar of icons that cost a request each then arrives in one fetch. Not a CoreFilter; enable it by name.

**Is sprite_images enabled by default?**

No. `sprite_images` is not in CoreFilters, the default RewriteLevel; it runs only when you enable it by name with `EnableFilters`.

**How do I enable sprite_images on Apache and nginx?**

Add `ModPagespeedEnableFilters sprite_images` on Apache or `pagespeed EnableFilters sprite_images;` on nginx. On IIS, add `pagespeed EnableFilters sprite_images` to pagespeed.config.

## Related filters

- [`convert_gif_to_png`](https://modpagespeed.com/docs/filters/convert_gif_to_png/): Convert GIF to PNG
- [`convert_jpeg_to_avif`](https://modpagespeed.com/docs/filters/convert_jpeg_to_avif/): Convert JPEG to AVIF
- [`convert_jpeg_to_progressive`](https://modpagespeed.com/docs/filters/convert_jpeg_to_progressive/): Progressive JPEG
- [`convert_jpeg_to_webp`](https://modpagespeed.com/docs/filters/convert_jpeg_to_webp/): Convert JPEG to WebP
- [`convert_png_to_jpeg`](https://modpagespeed.com/docs/filters/convert_png_to_jpeg/): Convert PNG to JPEG
- [`convert_to_avif_animated`](https://modpagespeed.com/docs/filters/convert_to_avif_animated/): Animated AVIF
- [`convert_to_avif_lossless`](https://modpagespeed.com/docs/filters/convert_to_avif_lossless/): Lossless AVIF
- [`convert_to_webp_animated`](https://modpagespeed.com/docs/filters/convert_to_webp_animated/): Animated WebP

This page is drawn from the [sprite_images entry on Image filters](https://modpagespeed.com/docs/image-filters/#sprite_images). Every filter in one table: [PageSpeed filters](https://modpagespeed.com/docs/filters/).