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.