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 then 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 based on all images with a specified tag.

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

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) or eagerly using an API call (limited to 500 images).

For example, four logos were uploaded to a demo product environment with the public IDs: amazon_logo, apple_logo, microsoft_logo and google_logo and thesprite_logo tag was assigned to all of them. The following URL delivers the generated sprite:

As you can see, a single vertical image was created 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.

As you can see, 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 is 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, version management is needed.

When a sprite is generated it is assigned a version, which is based on the time that it was created. You should use this version for accessing the CSS of the sprite. This way, your users will always get the most updated sprite.

You can eagerly generate/regenerate sprites by sending an HTTP POST request to the endpoint (replace 'demo' with your cloud name): https://api.cloudinary.com/v1_1/demo/image/sprite or using the relevant SDK sprite helper method.

For details on the required and optional parameters and for SDK syntax & examples, see the Sprite method in the Upload API Reference.

The sprite method call returns a JSON with the URLs for accessing the generated sprite image and css, including the version (v###) component:

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 4 logos, you probably noticed that each logo has a different size. If you want to display related images that share the same dimensions, you probably want to transform them before merging them into a single sprite.

You can provide transformation instructions while generating sprites (whether you are 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 will deliver 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 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: