# Types (/themes/sdk/reference/media/types)

```ts
import { … } from '@poltura/theme-sdk/media';
```

## `AssetRef` [#assetref]

A reference to a file under the theme's `assets/` folder, as `asset()` returns it.

```ts
type AssetRef = `asset://${string}`
```

## `MediaFormat` [#mediaformat]

An image file format a rendition can be served in.

```ts
type MediaFormat = 'webp' | 'avif' | 'jpg' | 'png' | 'svg'
```

## `MediaImageRef` [#mediaimageref]

An image a view model carries: the stored URL plus what was measured when it was uploaded.

<TypeTable type={{"url":{"description":"The stored image URL; `MediaImage` derives every rendition from it.","type":"string","required":true},"alt":{"description":"The alt text, or null when the image has none and the caller supplies its own.","type":"string | null","required":true},"width":{"description":"Width in pixels of the original upload, when it was measured.","type":"number","required":false},"height":{"description":"Height in pixels of the original upload, when it was measured.","type":"number","required":false},"hasAlpha":{"description":"Whether the image has transparent pixels, so it can sit on any background.","type":"boolean","required":false},"lqip":{"description":"A tiny inline placeholder shown while the image loads.","type":"string","required":false},"mime":{"description":"The MIME type of the original upload, such as `image/png`.","type":"string","required":false}}} />

## `MediaRole` [#mediarole]

The rendition an image is drawn at; each role has its own size and crop.

```ts
type MediaRole = 'thumb' | 'card' | 'tile' | 'pdp' | 'zoom' | 'hero' | 'og' | 'logo' | 'icon'
```

## `ResolvedMedia` [#resolvedmedia]

A media library file or theme asset, resolved for drawing.

<TypeTable type={{"id":{"description":"The file id, stable across edits.","type":"string","required":true},"url":{"description":"The URL of the stored original.","type":"string","required":true},"kind":{"description":"What the file is: a raster image, a video, an SVG or a document.","type":"'image' | 'video' | 'svg' | 'document'","required":true},"mimeType":{"description":"The MIME type of the stored original, such as `image/webp`.","type":"string","required":true},"width":{"description":"Width in pixels, or null when it was not measured.","type":"number | null","required":true},"height":{"description":"Height in pixels, or null when it was not measured.","type":"number | null","required":true},"durationMs":{"description":"Length of a video in milliseconds, or null for images.","type":"number | null","required":true},"alt":{"description":"The alt text in the shopper's language; `''` marks the image decorative.","type":"string","required":true},"focal":{"description":"The point the crop keeps in view, from 0 to 1 on each axis.","type":"{ readonly x: number; readonly y: number; }","required":true},"lqip":{"description":"A tiny inline placeholder shown while the file loads, or null.","type":"string | null","required":true},"hasAlpha":{"description":"Whether the image has transparent pixels.","type":"boolean","required":true},"poster":{"description":"The still frame shown before a video plays, or null.","type":"{ readonly url: string; readonly width: number | null; readonly height: number | null; readonly lqip: string | null; } | null","required":true}}} />

## `VideoValue` [#videovalue]

The value of a `video` setting: the source alone, or the source with how it plays.

```ts
type VideoValue = string | {
    readonly src: string;
    readonly poster?: string;
    readonly autoplay?: boolean;
    readonly loop?: boolean;
    readonly muted?: boolean;
    readonly alt?: string;
}
```

## `MediaImageProps` [#mediaimageprops]

Props of [`MediaImage`](/themes/sdk/reference/media/parts#mediaimage).

<TypeTable type={{"image":{"description":"A view model's image, or a media field's value (`media://`, `asset://` or an image URL).","type":"MediaImageRef | MediaValue","required":true},"role":{"description":"The rendition to draw, which sets the size and crop of every source; omitted, the one the URL names.","type":"MediaRole","required":false},"alt":{"description":"Alt text that overrides the image's own; empty keeps the image's own.","type":"string","required":false},"decorative":{"description":"A backdrop that carries no meaning: drawn with no alt text, whatever the image's own says.","type":"boolean","required":false},"className":{"description":"Classes added to the image.","type":"string","required":false},"sizes":{"description":"The `sizes` attribute, so the browser picks the right width.","type":"string","required":false},"priority":{"description":"Loads the image eagerly; reserve it for the largest image above the fold.","type":"boolean","required":false},"field":{"description":"The setting id the image came from, so the customizer can point at it when it fails.","type":"string","required":false},"fallback":{"description":"Drawn instead of the neutral placeholder while there is no picture to show.","type":"ReactNode","required":false}}} />

## `MediaPlaceholderProps` [#mediaplaceholderprops]

Props of [`MediaPlaceholder`](/themes/sdk/reference/media/parts#mediaplaceholder).

<TypeTable type={{"className":{"description":"Classes added to the placeholder.","type":"string","required":false},"label":{"description":"Read out when the missing image carried meaning; without it the placeholder is decorative.","type":"string","required":false},"width":{"description":"Width of the frame the image would fill, which sets the aspect ratio.","type":"number","required":false},"height":{"description":"Height of the frame the image would fill, which sets the aspect ratio.","type":"number","required":false}}} />

## `VideoSettingView` [#videosettingview]

A `video` setting ready to draw.

<TypeTable type={{"kind":{"description":"A file the page plays itself, or a YouTube or Vimeo player.","type":"'file' | 'embed'","required":true},"src":{"description":"The file's URL, or the player's embed URL.","type":"string","required":true},"title":{"description":"The player's title, for an embed; null for a file.","type":"string | null","required":true},"poster":{"description":"The still shown before it plays, or null.","type":"string | null","required":true},"autoplay":{"description":"Whether it starts by itself; shoppers who ask for reduced motion get it paused.","type":"boolean","required":true},"loop":{"description":"Whether it starts over at the end.","type":"boolean","required":true},"muted":{"description":"Whether it plays without sound.","type":"boolean","required":true},"alt":{"description":"The text alternative, or null.","type":"string | null","required":true}}} />

## `SettingVideoProps` [#settingvideoprops]

Props of [`SettingVideo`](/themes/sdk/reference/media/parts#settingvideo).

<TypeTable type={{"value":{"description":"The `video` setting's value.","type":"VideoValue | undefined","required":true},"cover":{"description":"Fills a positioned parent edge to edge as a backdrop, playing muted without controls.","type":"boolean","required":false},"className":{"description":"Classes merged onto the video or player.","type":"string","required":false}}} />