Assets in Uniform

The asset parameter and asset field each provide a seamless interface for adding media into a composition or content entry. The parameter can be configured to support multiple asset selection. Each asset may be from a different source. All assets have standard fields where you can add context-specific content, or connect to an external data source like a CMS or e-commerce system.

tip

For details on adding the asset parameter to a component, refer to the parameter guide. To add assets to a content type, refer to the field guide.

There are three ways to connect to an asset:

  1. Through an asset source
  2. From an existing data resource
  3. Via a custom URL

Choose assets from the built-in Uniform Asset Library, or connect to your existing DAM system or other asset sources by using integrations.

You can select assets from any existing data resource for entries. This is useful to select an image from the current product entry used to assemble a product detail page in Canvas.

Selecting this option provides a way to create an inline link to an image URL hosted elsewhere.

How to select an asset depends on the source of the asset. Once added, a preview of the image is shown and the current asset count updates.

info

The ability to select more than one asset depends on how you configure the parameter. You may need to remove an asset before being able to add a new one.

Once you have added an image to the asset parameter in a composition, you can:

  • Reorder assets: You can reorder assets by dragging and dropping them within the property panel of Canvas. This will change the order of items in the array in which they're delivered through the APIs.
  • Edit asset properties: If you click on an asset in the property panel, it will open in it in a modal. If the asset is sourced from the Uniform Asset Library, you can override the asset properties by selecting the Override for this parameter option in the menu.
  • Remove: If you click on an item in the property panel, it will open in it in a modal. Clicking "remove from selection" will remove the asset from the selection. The uploaded file and asset record (if applicable) won't be deleted. However, any customization of any properties will be lost.

info

When you edit an asset property from within a composition, you will override the information coming from the asset. Those changes aren't written back to the asset's source, like the asset library. The changes remain specific to the usage within the composition. If you edit the asset at the source, such as in the asset library, those changes will be present wherever the asset is used throughout the project.

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 assist 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 200x200, 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 200x200 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
Asset library