Sprite generation

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 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.

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).

Note
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:

Ruby:
Copy to clipboard
cl_image_tag("sprite_logo.png", :type=>"sprite")
PHP (cloudinary_php v1.x (legacy)):
Copy to clipboard
cl_image_tag("sprite_logo.png", array("type"=>"sprite"))
PHP (cloudinary_php v2.x):
Copy to clipboard
(new ImageTag('sprite_logo.png'))
  ->deliveryType('sprite');
Python:
Copy to clipboard
CloudinaryImage("sprite_logo.png").image(type="sprite")
Node.js:
Copy to clipboard
cloudinary.image("sprite_logo.png", {type: "sprite"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().type("sprite").imageTag("sprite_logo.png");
JS:
Copy to clipboard
cloudinary.imageTag('sprite_logo.png', {type: "sprite"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sprite_logo.png", {type: "sprite"})
React:
Copy to clipboard
<Image publicId="sprite_logo.png" type="sprite">

</Image>
Vue.js:
Copy to clipboard
<cld-image public-id="sprite_logo.png" type="sprite">

</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sprite_logo.png" type="sprite">

</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Action("sprite").BuildImageTag("sprite_logo.png")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setType( "sprite").generate("sprite_logo.png")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().type("sprite").generate("sprite_logo.png");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("sprite_logo.png")
deliveryType("sprite")
}.generate()
Logos 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:

Copy to clipboard
https://res.cloudinary.com/demo/image/sprite/logo.css
Copy to clipboard
.amazon_logo, .apple_logo, .google_logo, .microsoft_logo {
  background: url('//res.cloudinary.com/demo/image/sprite/v1630230323/sprite_logo.png') no-repeat;
}
.amazon_logo { background-position: 0px 0px; width: 162px; height: 38px; }
.apple_logo { background-position: 0px -40px; width: 206px; height: 250px; }
.google_logo { background-position: 0px -292px; width: 275px; height: 95px; }
.microsoft_logo { background-position: 0px -389px; width: 216px; height: 70px; }

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:

Copy to clipboard
<link rel="stylesheet" type="text/css" href="https://res.cloudinary.com/demo/image/sprite/sprite_logo.css">
...
...
<div class="amazon_logo"></div>

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:

Copy to clipboard
{
  css_url: 'https://res.cloudinary.com/demo/image/sprite/v1315740225/sprite_logo.css',
  image_url: 'https://res.cloudinary.com/demo/image/sprite/v1315740225/sprite_logo.png',
  secure_css_url: 
    'https://res.cloudinary.com/demo/image/sprite/v1315740225/sprite_logo.css',
  public_id: 'sprite_logo',
  version: '1315740225',
}

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

Copy to clipboard
<link href="https://res.cloudinary.com/demo/image/sprite/v1315740225/sprite_logo.css" 
      media="screen" rel="stylesheet" type="text/css" />

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:

Ruby:
Copy to clipboard
cl_image_tag("sprite_logo.png", :width=>150, :height=>60, :crop=>"fit", :type=>"sprite")
PHP (cloudinary_php v1.x (legacy)):
Copy to clipboard
cl_image_tag("sprite_logo.png", array("width"=>150, "height"=>60, "crop"=>"fit", "type"=>"sprite"))
PHP (cloudinary_php v2.x):
Copy to clipboard
(new ImageTag('sprite_logo.png'))
  ->resize(Resize::fit()->width(150)->height(60))
  ->deliveryType('sprite');
Python:
Copy to clipboard
CloudinaryImage("sprite_logo.png").image(width=150, height=60, crop="fit", type="sprite")
Node.js:
Copy to clipboard
cloudinary.image("sprite_logo.png", {width: 150, height: 60, crop: "fit", type: "sprite"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().width(150).height(60).crop("fit")).type("sprite").imageTag("sprite_logo.png");
JS:
Copy to clipboard
cloudinary.imageTag('sprite_logo.png', {width: 150, height: 60, crop: "fit", type: "sprite"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sprite_logo.png", {width: 150, height: 60, crop: "fit", type: "sprite"})
React:
Copy to clipboard
<Image publicId="sprite_logo.png" type="sprite">
  <Transformation width="150" height="60" crop="fit" />
</Image>
Vue.js:
Copy to clipboard
<cld-image public-id="sprite_logo.png" type="sprite">
  <cld-transformation width="150" height="60" crop="fit" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sprite_logo.png" type="sprite">
  <cl-transformation width="150" height="60" crop="fit">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Height(60).Crop("fit")).Action("sprite").BuildImageTag("sprite_logo.png")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setType( "sprite").setTransformation(CLDTransformation().setWidth(150).setHeight(60).setCrop("fit")).generate("sprite_logo.png")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().width(150).height(60).crop("fit")).type("sprite").generate("sprite_logo.png");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("sprite_logo.png")
resize(Resize.fit() {
width(150)
height(60)
})
deliveryType("sprite")
}.generate()
Transformed sprite

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:

Ruby:
Copy to clipboard
cl_image_tag("sprite_logo.png", :prefix=>"my_sprite_", :type=>"sprite")
PHP (cloudinary_php v1.x (legacy)):
Copy to clipboard
cl_image_tag("sprite_logo.png", array("prefix"=>"my_sprite_", "type"=>"sprite"))
PHP (cloudinary_php v2.x):
Copy to clipboard
# This code example is not currently available.
Python:
Copy to clipboard
CloudinaryImage("sprite_logo.png").image(prefix="my_sprite_", type="sprite")
Node.js:
Copy to clipboard
cloudinary.image("sprite_logo.png", {prefix: "my_sprite_", type: "sprite"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().prefix("my_sprite_")).type("sprite").imageTag("sprite_logo.png");
JS:
Copy to clipboard
cloudinary.imageTag('sprite_logo.png', {prefix: "my_sprite_", type: "sprite"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sprite_logo.png", {prefix: "my_sprite_", type: "sprite"})
React:
Copy to clipboard
<Image publicId="sprite_logo.png" type="sprite">
  <Transformation prefix="my_sprite_" />
</Image>
Vue.js:
Copy to clipboard
<cld-image public-id="sprite_logo.png" type="sprite">
  <cld-transformation prefix="my_sprite_" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sprite_logo.png" type="sprite">
  <cl-transformation prefix="my_sprite_">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Prefix("my_sprite_")).Action("sprite").BuildImageTag("sprite_logo.png")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setType( "sprite").setTransformation(CLDTransformation().setPrefix("my_sprite_")).generate("sprite_logo.png")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().prefix("my_sprite_")).type("sprite").generate("sprite_logo.png");
Kotlin:
Copy to clipboard
// This code example is not currently available.

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

Copy to clipboard
.my_sprite_google_logo, .my_sprite_apple_logo, 
.my_sprite_microsoft_logo, .my_sprite_amazon_logo {
  background: 
    url('https://res.cloudinary.com/demo/image/sprite/p_my_sprite_/v1315743843/sprite_logo.png') 
    no-repeat;
}
.my_sprite_google_logo { 
    background-position: 0px 0px; width: 275px; height: 95px; 
}
.my_sprite_apple_logo { 
    background-position: 0px -97px; width: 206px; height: 250px; 
}
.my_sprite_microsoft_logo { 
    background-position: 0px -349px; width: 216px; height: 70px; 
}
.my_sprite_amazon_logo { 
    background-position: 0px -421px; width: 162px; height: 38px; 
}

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

Copy to clipboard
<div class="my_sprite_amazon_logo"/>

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:
    Ruby:
    Copy to clipboard
    cl_image_tag("sprite_animals.png", :type=>"sprite", :transformation=>[
      {:aspect_ratio=>"1.0", :width=>85, :crop=>"fill"},
      {:radius=>10},
      {:angle=>-90}
      ])
    PHP (cloudinary_php v1.x (legacy)):
    Copy to clipboard
    cl_image_tag("sprite_animals.png", array("type"=>"sprite", "transformation"=>array(
      array("aspect_ratio"=>"1.0", "width"=>85, "crop"=>"fill"),
      array("radius"=>10),
      array("angle"=>-90)
      )))
    PHP (cloudinary_php v2.x):
    Copy to clipboard
    (new ImageTag('sprite_animals.png'))
      ->resize(Resize::fill()->width(85)->aspectRatio(1.0))
      ->roundCorners(RoundCorners::byRadius(10))
      ->rotate(Rotate::byAngle(-90))
      ->deliveryType('sprite');
    Python:
    Copy to clipboard
    CloudinaryImage("sprite_animals.png").image(type="sprite", transformation=[
      {'aspect_ratio': "1.0", 'width': 85, 'crop': "fill"},
      {'radius': 10},
      {'angle': -90}
      ])
    Node.js:
    Copy to clipboard
    cloudinary.image("sprite_animals.png", {type: "sprite", transformation: [
      {aspect_ratio: "1.0", width: 85, crop: "fill"},
      {radius: 10},
      {angle: -90}
      ]})
    Java:
    Copy to clipboard
    cloudinary.url().transformation(new Transformation()
      .aspectRatio("1.0").width(85).crop("fill").chain()
      .radius(10).chain()
      .angle(-90)).type("sprite").imageTag("sprite_animals.png");
    JS:
    Copy to clipboard
    cloudinary.imageTag('sprite_animals.png', {type: "sprite", transformation: [
      {aspectRatio: "1.0", width: 85, crop: "fill"},
      {radius: 10},
      {angle: -90}
      ]}).toHtml();
    jQuery:
    Copy to clipboard
    $.cloudinary.image("sprite_animals.png", {type: "sprite", transformation: [
      {aspect_ratio: "1.0", width: 85, crop: "fill"},
      {radius: 10},
      {angle: -90}
      ]})
    React:
    Copy to clipboard
    <Image publicId="sprite_animals.png" type="sprite">
      <Transformation aspectRatio="1.0" width="85" crop="fill" />
      <Transformation radius="10" />
      <Transformation angle="-90" />
    </Image>
    Vue.js:
    Copy to clipboard
    <cld-image public-id="sprite_animals.png" type="sprite">
      <cld-transformation aspect-ratio="1.0" width="85" crop="fill" />
      <cld-transformation radius="10" />
      <cld-transformation angle="-90" />
    </cld-image>
    Angular:
    Copy to clipboard
    <cl-image public-id="sprite_animals.png" type="sprite">
      <cl-transformation aspect-ratio="1.0" width="85" crop="fill">
      </cl-transformation>
      <cl-transformation radius="10">
      </cl-transformation>
      <cl-transformation angle="-90">
      </cl-transformation>
    </cl-image>
    .NET:
    Copy to clipboard
    cloudinary.Api.UrlImgUp.Transform(new Transformation()
      .AspectRatio("1.0").Width(85).Crop("fill").Chain()
      .Radius(10).Chain()
      .Angle(-90)).Action("sprite").BuildImageTag("sprite_animals.png")
    iOS:
    Copy to clipboard
    imageView.cldSetImage(cloudinary.createUrl().setType( "sprite").setTransformation(CLDTransformation()
      .setAspectRatio("1.0").setWidth(85).setCrop("fill").chain()
      .setRadius(10).chain()
      .setAngle(-90)).generate("sprite_animals.png")!, cloudinary: cloudinary)
    Android:
    Copy to clipboard
    MediaManager.get().url().transformation(new Transformation()
      .aspectRatio("1.0").width(85).crop("fill").chain()
      .radius(10).chain()
      .angle(-90)).type("sprite").generate("sprite_animals.png");
    Kotlin:
    Copy to clipboard
    cloudinary.image {
    publicId("sprite_animals.png")
    resize(Resize.fill() {
    width(85)
    aspectRatio(1.0f)
    })
    roundCorners(RoundCorners.byRadius(10))
    rotate(Rotate.byAngle(-90))
    deliveryType("sprite")
    }.generate()
    Transform and rotate
  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:
    Ruby:
    Copy to clipboard
    cl_image_tag("https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png", :angle=>90, :type=>"fetch")
    PHP (cloudinary_php v1.x (legacy)):
    Copy to clipboard
    cl_image_tag("https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png", array("angle"=>90, "type"=>"fetch"))
    PHP (cloudinary_php v2.x):
    Copy to clipboard
    (new ImageTag('https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png'))
      ->rotate(Rotate::byAngle(90))
      ->deliveryType('fetch');
    Python:
    Copy to clipboard
    CloudinaryImage("https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png").image(angle=90, type="fetch")
    Node.js:
    Copy to clipboard
    cloudinary.image("https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png", {angle: 90, type: "fetch"})
    Java:
    Copy to clipboard
    cloudinary.url().transformation(new Transformation().angle(90)).type("fetch").imageTag("https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png");
    JS:
    Copy to clipboard
    cloudinary.imageTag('https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png', {angle: 90, type: "fetch"}).toHtml();
    jQuery:
    Copy to clipboard
    $.cloudinary.image("https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png", {angle: 90, type: "fetch"})
    React:
    Copy to clipboard
    <Image publicId="https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png" type="fetch">
      <Transformation angle="90" />
    </Image>
    Vue.js:
    Copy to clipboard
    <cld-image public-id="https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png" type="fetch">
      <cld-transformation angle="90" />
    </cld-image>
    Angular:
    Copy to clipboard
    <cl-image public-id="https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png" type="fetch">
      <cl-transformation angle="90">
      </cl-transformation>
    </cl-image>
    .NET:
    Copy to clipboard
    cloudinary.Api.UrlImgUp.Transform(new Transformation().Angle(90)).Action("fetch").BuildImageTag("https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png")
    iOS:
    Copy to clipboard
    imageView.cldSetImage(cloudinary.createUrl().setType( "fetch").setTransformation(CLDTransformation().setAngle(90)).generate("https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png")!, cloudinary: cloudinary)
    Android:
    Copy to clipboard
    MediaManager.get().url().transformation(new Transformation().angle(90)).type("fetch").generate("https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png");
    Kotlin:
    Copy to clipboard
    cloudinary.image {
    publicId("https://res.cloudinary.com/demo/image/sprite/ar_1.0,c_fill,w_85/r_10/a_-90/v1630231462/sprite_animals.png")
    rotate(Rotate.byAngle(90))
    deliveryType("fetch")
    }.generate()
    Rotate and delivery a horizontal sprite image

✔️ Feedback sent!

Rate this page: