Create sprites

Overview

Sprites are a great way to improve user experience by reducing network overhead and bypassing download limitations.

A sprite is a single image that contains a vertical set of images. The browser downloads the single sprite image and your CSS code provides the browser with the coordinates of each image in the sprite.

Cloudinary can generate sprite images and the corresponding CSS files for you either on the fly based on images with a specified tag, or using the API based on either a tag, or a list of URLs.

For example, suppose you uploaded a set of corporate logos to your site. You could give them the tag 'sprite_logo' to easily generate a sprite that contains all of them.

You can assign tags to assets while uploading them, using our Cloudinary Console, or using the Upload API to add or remove tags on existing assets. See Tagging images and the tags method for more details.

Creating sprites on the fly

After you upload images and assign a tag to all the images you want to merge into a sprite, you are ready to dynamically create it.

The sprite and corresponding CSS code is automatically generated when you deliver a dynamic sprite URL that generates the sprite on demand when accessed for the first time (up to 100 images).

For example, you upload four logos to a demo product environment with the public IDs: amazon_logo, apple_logo, microsoft_logo and google_logo and apply the sprite_logo tag to all of them. The following URL delivers the generated sprite:

As you can see, this creates a single vertical image with all four logos, in alphabetical order by public ID.

To use the sprite in your HTML code, you need to reference the generated CSS of the sprite, which has the same URL as the sprite image, but with the .css extension:

The generated CSS and PNG files are automatically distributed through a CDN and smartly cached. Note that both the image and CSS of the sprite will be generated if they don't exist, whether you access the '.png' URL or the '.css' URL.

The CSS includes style class names for each of the four logos. The style class name is the public ID of the uploaded image asset.

To display an image from your sprite, include the CSS in your page and use the relevant style class name. For example, to display the Amazon logo, use the following HTML code:

Managing sprite versions

You might want to regenerate sprites when your content changes. In the example above, you would want to regenerate the sprite when adding a fifth logo or when replacing one of the four logos with a better quality or new design.

In such cases, you probably want your users to see the updated images right away after it's generated. However, the sprite assets are already cached on the users' browsers and in the CDN. To ensure immediate update of the sprite while still using high-performance cache and delivery techniques, you need version management.

When generating the URL, include a version number, for example v1234. This appears before the public ID in the URL.

For each new sprite you need to generate, change the version number.

You should use the same version for accessing the CSS of the sprite. This way, your users will always get the most updated sprite.

If you generate sprites using the API, the version number is returned in the JSON response:

To use the sprite in your HTML code, simply link to the generated CSS in your HTML page:

Applying transformations to sprites

In the example above with the four logos, you probably noticed that each logo has a different size. If you want to display related images that share the same dimensions, you may want to transform them before merging them into a single sprite.

You can provide transformation instructions while generating sprites (whether you're using the API for generating sprites or whether you access a dynamic URL of a sprite). Cloudinary will transform all images according to your instructions and generate a sprite with the transformed versions of the original images.

For example, the following URL delivers a sprite with the four images marked with the 'logo' tag while transforming each logo to fit in a 150x60 container:

Adding a custom prefix to sprite CSS files

You might need to prevent collisions with the style class names already used or in your site (for other sprites or static content). You can easily prevent such collisions by adding a 'prefix' parameter in your sprite CSS URL:

When this special p_ parameter is used, the generated CSS adds 'my_sprite_' as a prefix to all style class names:

To display the image in your site, reference the class name:

Delivering sprites horizontally

Sprites are generated vertically, and when using sprites for the main use case of delivering individual images from the sprite, the direction of course doesn't matter. However, it's possible to take advantage of automatically generated sprites to deliver the entire sprite as a single image on your site, for example, as a dynamically generated toolbar or as a thumbnail preview of images with the same tag.

If you want to deliver a complete sprite image horizontally, use the rotation transformations and fetch feature to accomplish this:

1. When generating the initial sprite, in addition to other transformations you may want to apply, use the angle transformation to rotate each image counter-clockwise by 90 degrees. Below, the images with the sprite_animals tag are resized to fill an 85x85px square with rounded corners and rotated counter clockwise:
   
2. When delivering the sprite in your page, use the fetch delivery type to deliver the generated sprite image URL with a 90 degree clockwise transformation applied:
   

Creating sprites with the API

Using the Upload API you can generate sprites from up to 500 images. You can generate a sprite either from a tag, or a list of URLs.

Send an HTTP POST request to the sprite endpoint (replace 'demo' with your cloud name): https://api.cloudinary.com/v1_1/demo/image/sprite or use the relevant SDK sprite helper method.

For details on the required and optional parameters, see the sprite method in the Upload API Reference.

Example 1: generate a sprite from a tag

Generate a sprite from all images tagged with logo. It creates a single PNG image file with the public ID of logo that contains all the tagged images, and a CSS file with the public ID of logo.css.

This is the response:

Example 2: generate a sprite from a list of URLs

Generate a sprite from three image URLs and set the format of the sprite to WebP. It creates a single WebP image file with a random public ID that contains all the images specified, and a CSS file with the same random public ID and .css extension.

This is the response: