# Hooks (/themes/sdk/reference/media/hooks)

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

## `useMedia` [#usemedia]

The media library file or theme asset a media field's value names.

```ts
useMedia(value: MediaValue | null): ResolvedMedia | null
```

**Parameters**

- `value: MediaValue | null`: The media field's value.

**Returns:** The resolved file, or null while it loads, when it is gone or when the value is not a reference.

**Example**

```tsx
import { useMedia } from '@poltura/theme-sdk/media';

export function Caption({ image }: { image: string }) {
  const media = useMedia(image);
  return media === null ? null : <figcaption>{media.alt}</figcaption>;
}
```

## `useMediaDrawn` [#usemediadrawn]

Whether a media field's value draws a picture, so a layout can drop the frame when it does not.

```ts
useMediaDrawn(value: MediaValue | null): boolean
```

**Parameters**

- `value: MediaValue | null`: The media field's value.

**Returns:** True for an image URL or a file that draws a picture, false when unset or missing.

**Example**

```tsx
import { MediaImage, useMediaDrawn } from '@poltura/theme-sdk/media';

export function Banner({ image }: { image: string }) {
  return useMediaDrawn(image) ? <MediaImage image={image} role='hero' /> : null;
}
```

## `useThemeAsset` [#usethemeasset]

A theme asset as media renderers read it.

```ts
useThemeAsset(path: string): ResolvedMedia | null
```

**Parameters**

- `path: string`: The path inside `assets/`.

**Returns:** The resolved asset, or null when the theme has no such file.

**Example**

```tsx
import { useThemeAsset } from '@poltura/theme-sdk/media';

export function PatternSize() {
  const pattern = useThemeAsset('images/pattern.png');
  return <span>{pattern?.width ?? 0}</span>;
}
```

## `useAssetUrl` [#useasseturl]

The URL a theme asset loads from: one rendition of an image with a role, otherwise the file whole.

```ts
useAssetUrl(path: string, role?: MediaRole): string | null
```

**Parameters**

- `path: string`: The path inside `assets/`.
- `role?: MediaRole`: The rendition to load; SVGs, fonts and icons always load whole.

**Returns:** The URL, or null when the theme has no such file.

**Example**

```tsx
import { useAssetUrl } from '@poltura/theme-sdk/media';

export function Texture() {
  const url = useAssetUrl('images/paper.jpg', 'tile');
  return url === null ? null : <div style={{ backgroundImage: `url(${url})` }} />;
}
```

## `useVideoSetting` [#usevideosetting]

A `video` setting resolved to the file or player it plays, with its poster and how it plays.

```ts
useVideoSetting(value: VideoValue | undefined): VideoSettingView | null
```

**Parameters**

- `value: VideoValue | undefined`: The setting's value.

**Returns:** The video, or null when the setting is empty or its file is gone.

**Example**

```tsx
import { useVideoSetting, type VideoValue } from '@poltura/theme-sdk/media';

export function VideoCaption({ video }: { video?: VideoValue }) {
  const view = useVideoSetting(video);
  return view?.alt ? <figcaption>{view.alt}</figcaption> : null;
}
```