# Asset parameter

> Use the asset parameter to add, select, upload, and edit assets directly from a composition or entry.

Source: https://docs.uniform.app/docs/guides/composition/manage-assets/asset-parameter

The **Asset parameter** is how editors add media to a composition, entry, or pattern. The parameter can hold one or more assets, sourced from the [Uniform Asset Library](https://docs.uniform.app/docs/guides/composition/manage-assets/asset-library), connected DAM systems, a [data resource](#data-resources), or a [custom URL](#custom-url). Each asset carries the metadata needed to deliver optimized media across any channel.

> **Tip:**
>
> For details on adding the asset parameter to a component, refer to the [parameter guide](https://docs.uniform.app/docs/guides/models/components/parameters#asset). To add assets to a content type, refer to the [field guide](https://docs.uniform.app/docs/guides/models/content-types/fields).

## Asset sources

An asset parameter can pull from several different sources. Each source surfaces in the [asset selector](#asset-selector) sidebar with its own search, filtering, and preview interface.

### Uniform Asset Library and DAM integrations

Pick assets from the built-in [Uniform Asset Library](https://docs.uniform.app/docs/guides/composition/manage-assets/asset-library) or from a connected DAM by using [integrations](https://docs.uniform.app/docs/integrations/dam).

### Data resources

You can select assets from any existing [data resource for entries](https://docs.uniform.app/docs/guides/composition/entries/using-entries#using-entries-in-compositions-and-patterns). For example, this is useful when you want to use an image from the current product entry on a component in a product detail page.

When the selected data resource exposes a focal point, the parameter automatically connects the asset's focal point field to the data resource's focal point. See [connect the focal point to a data resource](https://docs.uniform.app/docs/guides/composition/manage-assets/asset-editor#connect-the-focal-point-to-a-data-resource).

### Custom URL

The **Custom** source lets you point the parameter at an arbitrary external URL that is publicly accessible. The URL field accepts [dynamic tokens](https://docs.uniform.app/docs/guides/composition/connect-external-data/data-resources#dynamic-tokens), so the URL can be resolved at runtime from a data resource.

Only `http(s)` URLs are supported. Once the URL is locked in, the view switches to the [Edit asset](#edit-asset) pane so you can supply a title, description, and other metadata.

## Asset parameter appearance

When you open a composition, entry, or pattern that has an asset parameter, the parameter renders inline on the property panel. Its layout varies depending on whether it is empty, or set up for single or multiple assets.

### No assets selected

When no assets are selected, a wide drop zone appears, inviting users to add assets by dropping a file or uploading from their computer. Inside the drop zone, beneath the upload prompt, icons are shown for the Uniform Asset Library and each connected DAM integration (such as Cloudinary or Bynder). You can:

- **Drop a file** anywhere on the drop zone to upload an asset directly.
- Click the drop zone to **browse for a file** to upload.
- Click any **asset source icon** to jump straight into the [Add to selection](#add-to-selection) step for that source.

![Empty asset parameter with drop zone and asset source icons.](https://docs.uniform.app/images/guides/composition/assets/asset-parameter-empty.png)

### Single asset allowed

When the asset parameter is set up to hold a single asset, the property panel shows a single, large thumbnail of the asset. You can:

- **Drop a file** onto the thumbnail to swap the asset (a _Drop to swap_ overlay appears while you drag). See [drag-and-drop upload and swap](#drag-and-drop-upload-and-swap).
- Click the **Edit** button or click on the thumbnail to open the asset's detail view in the [asset selector](#asset-selector), where you can swap, edit, or remove the asset.

![Asset parameter with a single image thumbnail and Edit button.](https://docs.uniform.app/images/guides/composition/assets/asset-parameter-single.png)

### Multiple assets allowed

When the parameter holds multiple assets, the property panel shows a grid of thumbnails with drag handles. You can:

- **Reorder** assets by dragging them. The order is preserved in the API response.
- **Drop a file** onto a thumbnail to swap that specific asset, or onto the _add more_ tile to append a new asset to the selection.
- Click **Edit** on any item to manage the [current selection](#current-selection) in the [asset selector](#asset-selector).

![Asset parameter with a row of image thumbnails and an upload tile.](https://docs.uniform.app/images/guides/composition/assets/asset-parameter-multi.png)

## Asset selector

Clicking **Edit** on the canvas opens a modal with multiple views for selecting, editing, and managing assets on the parameter. You switch between views using the buttons in the modal header.

### Current selection

This is the default view when the parameter holds more than one asset. The header shows a counter of currently selected assets, with **Remove all** and **Add to selection** actions on the right.

- Click any asset in the grid to open it in the [Edit asset](#edit-asset) view.
- Click the  icon on a thumbnail to remove it from the selection. Removing a [transient asset](#transient-assets) also deletes its uploaded file.

![Asset selector modal on the Current selection step, showing three selected images in a grid with Remove all and Add to selection actions in the header.](https://docs.uniform.app/images/guides/composition/assets/asset-selector-current-selection.png)

### Add to selection

Click **Add to selection** (in either the current selection view or directly from the empty state) to open the source picker.

The **sidebar** on the left lists the available [asset sources](#asset-sources):

- **Uniform Asset Library**: search, filter, sort, and pick from your project's library. The sidebar also shows a quick filter by [labels](https://docs.uniform.app/docs/guides/composition/manage-assets/asset-labels#filter-assets-by-label).
- **Integrations**: each configured DAM (Cloudinary, Bynder, Scaleflex, and so on) appears as its own source.
- **Data resources**: sources backed by [data resources](#data-resources).
- **Custom**: point at an external [custom URL](#custom-url).

The **right pane** renders the picker for the selected source. For the Uniform Asset Library this is the same list interface as the standalone [asset library](https://docs.uniform.app/docs/guides/composition/manage-assets/asset-library). Use the **Upload New** button in the toolbar to switch the right pane to a dedicated upload view, or drop files anywhere on the grid to start uploading.

Your search, filter, and sort state is remembered as you navigate.

![Asset selector modal on the Add to selection step, showing the source sidebar on the left and a grid of assets from the Uniform Asset Library on the right.](https://docs.uniform.app/images/guides/composition/assets/asset-selector.png)

### Edit asset

The Edit asset view is the in-modal detail page for a single selected asset. The layout mirrors the standalone [asset editor](https://docs.uniform.app/docs/guides/composition/manage-assets/asset-editor):

- **Preview** on the left (with expand/collapse).
- **Properties** on the right (title, description, labels, focal point).
- **Meta** section with ID, media type, size, URL, dimensions, and **Created** / **Modified** with author.
- **Usage** section showing where this asset is referenced.

The header also shows the [overrides pill](#overrides) when the asset is sourced from the Uniform Asset Library. Click **Remove** in the top-right to remove the asset from the parameter selection. The underlying asset record (if any) is not deleted.

### Edit original asset

For assets sourced from the Uniform Asset Library, the modal offers a fourth view that lets you edit the original asset record without leaving the visual editor. You can reach it by:

- Opening the [overrides pill](#overrides) and selecting **Edit original**, or
- Uploading a brand-new asset through the parameter, which opens the modal straight on this view so you can fill out the new asset's metadata.

Edits made here update the original asset and apply everywhere it's used. See the [asset editor guide](https://docs.uniform.app/docs/guides/composition/manage-assets/asset-editor) for everything available in this view, including [replacing the underlying file](https://docs.uniform.app/docs/guides/composition/manage-assets/asset-editor#replace-the-asset-file) and [deleting the asset](https://docs.uniform.app/docs/guides/composition/manage-assets/asset-editor#delete-an-asset).

## Overrides

When an asset is sourced from the Uniform Asset Library, any property you edit on the parameter becomes an **override** that only applies to this usage. The original asset in the library is not modified.

The **Overrides pill** at the top of the asset's detail view shows the current state:

- **Original**: the parameter is using the unmodified library values.
- **Overrides**: at least one property has been overridden for this usage.

Open the pill menu for two actions:

- **Edit original**: opens the [Edit original asset](#edit-original-asset) view to change the library record itself. Updates propagate to every usage.
- **Reset changes**: clears all overrides, reverting the parameter to the library values.

> **Info:**
>
> Editing a property from inside a composition only affects this usage. The original asset in the library remains untouched. To change the asset everywhere, use **Edit original** instead.

> **Tip:**
>
> You can use [AI quick edits](https://docs.uniform.app/docs/guides/ai/ai-quick-edits#quick-edits-for-asset-parameters) to modify asset overrides directly from the editor.

## Transient assets

When you upload a new file from inside an asset parameter (drop-to-upload, file picker, or the **Upload New** button), Uniform creates a _transient asset_:

1. The file is uploaded to Uniform's storage immediately.
2. The asset record is **not** added to the asset library yet; it lives only on the parameter.
3. The parameter shows the asset with a **New** chip.
4. When you save the composition or entry, Uniform persists the transient asset to the library and clears the _New_ state.
5. If you remove the transient asset from the parameter before saving, the uploaded file is deleted automatically.

This means editors can experiment with uploads without polluting the asset library. Nothing leaks into the library unless the composition or entry is actually saved.

## Drag-and-drop upload and swap

The asset parameter exposes two complementary drop targets:

- **The drop zone** (full-width on the empty state, compact on the multi-asset _add more_ tile) accepts one or more files and adds each as a new asset on the parameter.
- **Drop-to-swap on a thumbnail** swaps the asset at that position with the dropped file. When you drop multiple files onto a thumbnail, the first file replaces the asset at that position; any additional files are inserted into the selection immediately after.

Both targets work simultaneously. You can drag a file onto a specific thumbnail to swap it, or onto the empty space below the grid to append, without ambiguity about which target receives the drop.

## Connect to a dynamic value

By default, the asset parameter stores the assets that the editor picks directly. A connection menu lets you replace that selection with a dynamic value that resolves at runtime, so the parameter is filled by an upstream system instead.

- **Connect to Uniform asset**: connect the parameter to a dynamic-token expression.
- **Connect to custom URL**: shortcut that opens the parameter modal directly on the [Custom URL](#custom-url) source.
- **Disconnect from Uniform asset**: convert the dynamic value back into a static value.

## Asset properties and rendering

For the shape of the asset parameter value returned by the API, the `imageFrom` utility, TypeScript types, and framework-specific rendering guidance, see [rendering assets](https://docs.uniform.app/docs/guides/composition/manage-assets/rendering-assets).

> **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).