Developers
Start building
Themes/Theme SDK/Modules/media/Hooks

Hooks

The hooks of @poltura/theme-sdk/media.

On this page
import { … } from '@poltura/theme-sdk/media';

useMedia

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

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

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

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

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

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

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

useThemeAsset

A theme asset as media renderers read it.

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

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

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

useAssetUrl

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

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

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

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

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

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;
}
Last updated