Rendering assets

This page describes the shape of the asset parameter value returned by the Uniform APIs and the SDK utilities you can use to render assets in your frontend. For the editor-facing flow, see the asset parameter. For configuration options when defining the parameter on a component, see parameters for components.

The asset parameter provides a composition with a set of properties about an asset, reducing or eliminating the need to model them as separate component parameters. The data within the asset parameter is returned as an array, even if the array only contains one item.

API responses include these fields:

ParameterDescriptionAllowed valuesRequired
typeBroad category of the assetimage, video, audio, otherYes
_sourceInternal field indicating the source of the image. It could be an integration ID, a data resource name, or a custom stringuniform-assets, <string>No
_idRandom, persisted UUID assigned to the asset parameter array item to assist with frontend rendering (for example, as a value for the React key property). This is not the ID of the asset, which is instead found in the fields.id property.<UUID string>Yes
fields.idID of the asset{ type: 'text', value: '<UUID string>' }No
fields.urlURL pointing to the binary file{ type: 'text', value: '<URL>' }Yes
fields.titleTitle of the asset{ type: 'text', value: '<STRING>' }No
fields.descriptionDescription of the asset{ type: 'text', value: '<STRING>' }No
fields.mediaTypeMedia (mime) type of the asset{ type: 'text', value: '<STRING>' }No
fields.widthWidth of the asset (in case of an image){ type: 'number', value: <NUMBER> }No
fields.heightHeight of the asset (in case of an image){ type: 'number', value: <NUMBER> }No
fields.focalPointFocal point of the asset (in case of an image){ type: 'focalPoint', value: { x: <NUMBER>, y: <NUMBER> } }No

In the context of a composition, the response from the API would be structured like this:

"asset": { "type": "asset", "value": [ { "type": "image", "_id": "69197033-6dcb-49f2-91bf-a3c8246ff8ee", "_source": "uniform-assets", "fields": { "id": { "type": "text", "value": "69197033-6dcb-49f2-91bf-a3c8246ff8ee" }, "url": { "type": "text", "value": "https://img.uniform.global/p/j52GAt4USny1AmTCdiwADQ/jvbDipiiQT6v94H0dD1NeA-some-image.png", }, "title": { "type": "text", "value": "Asset Title", }, "description": { "type": "text", "value": "This is an image showing something interesting", }, "mediaType": { "type": "text", "value": "image/png", }, "width": { "type": "number", "value": 1000, }, "height": { "type": "number", "value": 563, }, "focalPoint": { "type": "focalPoint", "value": { "x": 0.5, "y": 0.5, }, }, }, }, ] },

Asset utilities are provided by the Uniform SDK to streamline the process of rendering assets in your application.

For interacting with the Image Delivery API, an imageFrom utility is available, exported from the @uniformdev/assets package. The utility assists with the following:

  1. Extracting a URL from an asset parameter
  2. Constructing a URL compatible with the Image Delivery API transformations, for assets sourced from the Uniform Asset Library
import { imageFrom } from '@uniformdev/assets' const assetParameter = { ... }; for (const asset of assetParameter.value) { // Log the URL of the asset from the asset parameter console.log(imageFrom(asset).url()); } for (const asset of assetParameter.value) { // Resize the image to 100x100, with the focal point set to the top left corner console.log(imageFrom(asset).transform({ width: 100, height: 100, focal: { x: 0, y: 0 } }).url()); } for (const asset of assetParameter.value) { // Fit the image to a 100x100 box, but don't crop console.log(imageFrom(asset).transform({ width: 100, height: 100, fit: 'scale-down' }).url()); } // You can also pass in a URL directly imageFrom('https://img.uniform.global/p/...').transform({ width: 1200 }).url();

tip

The imageFrom utility will automatically respect the focal point of the asset passed to it if present, you do not need to manually pass it in.

info

Calls to .transform() will be ignored for non-image assets, and any assets not sourced from the Uniform Asset Library. In those cases, the original URL will always be returned.

The assets SDK (available under @uniformdev/assets) exports types that can be useful when rendering assets in your application.

import type { /** A type for a whole array representing the value of an asset parameter **/ AssetParamValue, /** A type of a single array item representing the asset parameter item payload **/ AssetParamValueItem, /** Image delivery parameters type **/ ImageDeliveryParams, } from '@uniformdev/assets'

When rendering images coming from the Uniform Asset Library, you will need to follow a few steps:

  1. Enable images coming from the Uniform CDN

In your next.config.ts file, add img.uniform.global as an allowed remote pattern:

const nextConfig = { ... images: { remotePatterns: [ { protocol: 'https', hostname: 'img.uniform.global', }, ], }, }
  1. Use the imageFrom utility documented above in combination with the Image component:
import { imageFrom } from '@uniformdev/assets' const [firstAsset] = assetsParameter return ( <Image src={imageFrom(firstAsset).transform({ width: 1200 }).url()} // We need a ?? fallback because the width and height are required by the Next.js Image component, // but are not guaranteed to be present on every asset parameter, specifically for assets // not sourced from the Uniform Asset Library width={firstAsset.fields.width?.value ?? 1200} height={firstAsset.fields.height?.value ?? 800} alt={firstAsset.fields.description?.value ?? ''} /> )
  1. For background images you can use the Image component together with the fill property, like so:
return ( <div style={{ width: '400px', height: '400px', position: 'relative', }} > <Image // The focal point property of an asset is automatically respected by `transform` and does not need to be passed in src={imageFrom(firstAsset).transform({ width: 400, height: 400 }).url()} alt={firstAsset.fields.description?.value ?? ''} fill /> </div> )
Last modified
Next
Image Delivery API