# Asset Parameter Utilities

> How to work with asset parameters using flattenValues from the Uniform canvas SDK.

Source: https://docs.uniform.app/docs/sdk/parameter-utilities/asset-parameters

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.

```tsx
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:

```tsx
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

```tsx
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`](https://github.com/uniformdev/agent-skills/tree/main/skills/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](https://docs.uniform.app/docs/guides/ai/agent-skills).