---
title: "imageMedia"
description: "An image from a URL prop, fitted into the layer."
group: "paint"
groupTitle: "Painting"
categoryId: "media"
categorySlug: "media"
categoryTitle: "Media"
kind: "function"
sourceUrl: "https://github.com/shader-effects-inc/shaders/blob/main/packages/core/src/std/paint/media.ts#L81"
---

# imageMedia

An image from a URL prop, fitted into the layer.

```ts
imageMedia(opts: MediaFitSlots & {
    /** The URL prop. */
    src: PropRef
    /** A debug label for the texture, shown in GPU tooling. */
    label: string
    /** Called when the image fails to load. */
    onError?: (error: unknown, url: string) => void
}): MediaSurfaceHalf
```

Import `media` from `shaders/std` and use `media.imageMedia`.

The layer is transparent until the image loads, then shows it at its real aspect ratio. Set `naturalSizeKey: {fromProp: 'url'}` on the definition so layout can measure the image. `onError` receives load failures with the URL so you can phrase the message.

## Parameters

| Name | Type | Notes |
|---|---|---|
| `opts` | `MediaFitSlots & {
    /** The URL prop. */
    src: PropRef
    /** A debug label for the texture, shown in GPU tooling. */
    label: string
    /** Called when the image fails to load. */
    onError?: (error: unknown, url: string) => void
}` |  |

## Example

```ts
...imageMedia({src: p('url'), fit: p('objectFit'), decode: 'srgb-linear-alpha-cut', label: 'Photo'})
```

## See also

- [`videoMedia`](/docs/primitives/media/videomedia) — A video from a URL prop, playing in the layer.
- [`webcamMedia`](/docs/primitives/media/webcammedia) — The user's camera, live in the layer.

## Used by

[ImageTexture](/docs/components/imagetexture)