Asset Parameter Utilities

Asset parameters store references to images, videos, and other media files managed through Uniform's asset library or connected DAM integrations.

Using flattenValues#

Use flattenValues from @uniformdev/canvas to extract asset data from ComponentParameter<AssetParamValue> values. This utility normalizes the parameter structure into a usable format.

import { AssetParamValue, flattenValues } from "@uniformdev/canvas"; import { ComponentParameter, ComponentProps } from "@uniformdev/next-app-router/component"; type GalleryProps = { images?: ComponentParameter<AssetParamValue>; featuredImage?: ComponentParameter<AssetParamValue>; }; export const GalleryComponent = ({ parameters: { images, featuredImage }, }: ComponentProps<GalleryProps>) => { // Multiple assets: returns an array const allImages = flattenValues(images); // Single asset: returns a single object const hero = flattenValues(featuredImage, { toSingle: true }); return ( <div> {hero && ( <img src={hero.url} width={hero.width} height={hero.height} alt={hero.fields?.alt?.value ?? ""} /> )} <div className="grid grid-cols-3 gap-4"> {allImages?.map((img, i) => ( <img key={i} src={img?.url} width={img?.width} height={img?.height} /> ))} </div> </div> ); };

flattenValues options#

Option	Type	Default	Description
`toSingle`	`boolean`	`false`	When `true`, returns a single asset object instead of an array. Use for parameters that contain exactly one asset.

Returned asset object#

Each flattened asset object contains:

Property	Type	Description
`url`	`string`	The URL of the asset
`width`	`number`	Width in pixels (images)
`height`	`number`	Height in pixels (images)
`fields`	`object`	Additional metadata fields (e.g., `alt`, `title`, `description`)
`mediaType`	`string`	MIME type of the asset

Accessing asset metadata fields#

Asset metadata (like alt text) is stored in the fields property:

const image = flattenValues(heroImage, { toSingle: true }); const alt = image?.fields?.alt?.value ?? ""; const title = image?.fields?.title?.value ?? ""; const description = image?.fields?.description?.value ?? "";

Using with Next.js Image#

import Image from "next/image"; import { AssetParamValue, flattenValues } from "@uniformdev/canvas"; import { ComponentParameter, ComponentProps } from "@uniformdev/next-app-router/component"; type HeroProps = { backgroundImage?: ComponentParameter<AssetParamValue>; }; export const HeroComponent = ({ parameters: { backgroundImage }, }: ComponentProps<HeroProps>) => { const image = flattenValues(backgroundImage, { toSingle: true }); if (!image?.url) return null; return ( <Image src={image.url} alt={image.fields?.alt?.value ?? ""} width={image.width} height={image.height} priority /> ); };

warning

Always use flattenValues from @uniformdev/canvas for asset parameters. Do not create custom utility functions for extracting asset data.

Use an AI coding assistant

The uniform-assets agent skill teaches coding assistants such as Claude Code, Codex, Cursor, and Copilot how to define asset parameters, render images with imageFrom, read asset fields, and seed or migrate asset values. To install it, see Uniform agent skills.