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 Management Console, or using the Upload API to add or remove tags on existing assets. See Tagging images and the Tags method for more details.
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).
Delivering sprites using dynamic URLs is disabled by default for all new accounts. You can enable this from the security settings of the Cloudinary Management Console under Restricted media types. If you enable Sprites and you are using randomized public IDs for security reasons, you should also make sure you are not using guessable tags.
For example, we uploaded four logos to our demo account with the public IDs: amazon_logo, apple_logo, microsoft_logo and google_logo. We assigned the tag sprite_logo to all of them. The following URL delivers the generated sprite:
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:
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:
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:
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:
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:
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: