Apply asset renditions to customize images
When content creators customize an image asset in content items, Kontent.ai saves the customization as an asset rendition.
Let's go through how to apply asset renditions in your app so that the images are displayed just as content creators intended.
Table of contents
Key points
- An asset rendition is a customized version of an image asset.
- To apply an asset rendition in your app, get a content item with an image and add the rendition parameters to the image's URL.
- You can combine asset renditions with image transformation to optimize the customized images for each channel your app serves.
What is an asset rendition
An asset rendition crops and resizes the image it's applied to. Using a rendition on an image doesn't modify the original image. It creates additional metadata that tells your app which part of the image to display.
Combine renditions with image transformation
When you develop your app, you use image transformation to optimize the images for each channel where your app displays the content.
Asset renditions use a subset of the image transformation URL parameters. Combine asset renditions with image transformation to optimize the customized images by adjusting their size, format, or compression.
Apply asset renditions in code
When you retrieve a content item with a customized image asset, the asset element in the API response comes with an asset rendition.
In the JSON example below, teaser_image is the asset element object that contains the image. In the asset's value, notice the renditions property, which specifies how to customize the image.
"teaser_image": { "type": "asset", "name": "Teaser image", "value": [ { "name": "construction-insurance-header.jpg", "description": null, "type": "image/jpeg", "size": 402916, "url": "https://assets-us-01.kc-usercontent.com:443/8d20758c-d74c-4f59-ae04-ee928c0816b7/7bf69996-30a0-49b0-ad8c-09f6e0a04e44/construction-insurance-header.jpg", "width": 2124, "height": 767, "renditions": { "default": { "rendition_id": "b6ed90d0-e544-4b93-9212-fc041279fa90", "preset_id": "a6d98cd5-8b2c-4e50-99c9-15192bce2490", "width": 600, "height": 300, "query": "w=600&h=300&fit=clip&rect=1247,183,600,300" } } } ] }"teaser_image": { "type": "asset", "name": "Teaser image", "value": [ { "name": "construction-insurance-header.jpg", "description": null, "type": "image/jpeg", "size": 402916, "url": "https://assets-us-01.kc-usercontent.com:443/8d20758c-d74c-4f59-ae04-ee928c0816b7/7bf69996-30a0-49b0-ad8c-09f6e0a04e44/construction-insurance-header.jpg", "width": 2124, "height": 767, "renditions": { "default": { "rendition_id": "b6ed90d0-e544-4b93-9212-fc041279fa90", "preset_id": "a6d98cd5-8b2c-4e50-99c9-15192bce2490", "width": 600, "height": 300, "query": "w=600&h=300&fit=clip&rect=1247,183,600,300" } } } ] }
To get the customized version of the image, append the query value to the image URL you find in the url property.
You can let the SDK apply asset renditions when they're available. Because content creators can create only a single customization per image, it's safe to set a default rendition for all images.
To do that, provide the defaultRenditionPreset configuration option when initializing the Delivery client.
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript const KontentDelivery = require('@kontent-ai/delivery-sdk'); // Specifies which asset rendition to use by default by providing defaultRenditionPreset const deliveryClient = KontentDelivery.createDeliveryClient({ environmentId: '<YOUR_ENVIRONMENT_ID>', // Automatically applies the 'default' asset rendition if assets specify it defaultRenditionPreset: 'default' }); // Requests a content item const response = await deliveryClient.item('my_article') .toPromise(); // Gets the first asset in the 'teaser_image' asset element const asset = response.data.item.elements.teaser_image.value[0]; // Gets the asset's URL. If the asset specifies a rendition, it's automatically applied. const assetUrl = asset.url;// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript const KontentDelivery = require('@kontent-ai/delivery-sdk'); // Specifies which asset rendition to use by default by providing defaultRenditionPreset const deliveryClient = KontentDelivery.createDeliveryClient({ environmentId: '<YOUR_ENVIRONMENT_ID>', // Automatically applies the 'default' asset rendition if assets specify it defaultRenditionPreset: 'default' }); // Requests a content item const response = await deliveryClient.item('my_article') .toPromise(); // Gets the first asset in the 'teaser_image' asset element const asset = response.data.item.elements.teaser_image.value[0]; // Gets the asset's URL. If the asset specifies a rendition, it's automatically applied. const assetUrl = asset.url;
Now whenever you access the asset's URL, the asset rendition is applied for you automatically.
When you a get content item with an asset, check if the asset specifies an asset rendition and apply it.
// Initializes a Delivery client _client = DeliveryClientBuilder .WithOptions(builder => builder .WithProjectId("<YOUR_PROJECT_ID>") .UseProductionApi() .Build()) .Build(); // Retrieves a content item var response = await _client.GetItemAsync<Article>("my_article"); // Gets the image from an asset element named Teaser Image var imageWithRendition = response.Item.TeaserImage.SingleOrDefault(x => x.Name == "construction-insurance-header.jpg"); // Gets the asset rendition query from the image var renditionQuery = imageWithRendition.Renditions["default"].Query; // Combines the original image URL with the asset rendition query, if the image specifies a query var assetUrl = $"{imageWithRenditions.Url}?{renditionQuery}";// Initializes a Delivery client _client = DeliveryClientBuilder .WithOptions(builder => builder .WithProjectId("<YOUR_PROJECT_ID>") .UseProductionApi() .Build()) .Build(); // Retrieves a content item var response = await _client.GetItemAsync<Article>("my_article"); // Gets the image from an asset element named Teaser Image var imageWithRendition = response.Item.TeaserImage.SingleOrDefault(x => x.Name == "construction-insurance-header.jpg"); // Gets the asset rendition query from the image var renditionQuery = imageWithRendition.Renditions["default"].Query; // Combines the original image URL with the asset rendition query, if the image specifies a query var assetUrl = $"{imageWithRenditions.Url}?{renditionQuery}";
Asset renditions in practice
If you use the image asset URL on its own, you get the original image without any renditions applied.
The original image.
When you combine the URL with the query string parameters, you get the customized image's URL.
https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/7bf69996-30a0-49b0-ad8c-09f6e0a04e44/construction-insurance-header.jpg?w=600&h=300&fit=clip&rect=1247,183,600,300https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/7bf69996-30a0-49b0-ad8c-09f6e0a04e44/construction-insurance-header.jpg?w=600&h=300&fit=clip&rect=1247,183,600,300
The original image customized by the rendition's query parameters.