HtMedia

Media from a URL that can be an image or a video: renders an HtVideo when src ends in a video extension, and an HtImage otherwise. alt names either one: the image's alt, or the video's aria-label. An empty alt names a video player "Video" and hides a video without controls. decorative hides either one from screen readers, and a decorative video shows no controls and shows its first frame by default.

Use HtImage or HtVideo when the URL is always one kind.

#Example

#Usage

#Text alternative

HtMedia requires either alt or decorative, like HtImage. An image renders alt as its text alternative, and a video renders it as its aria-label.

An empty alt and a decorative video follow the HtVideo rules. An empty alt names a video player "Video" and hides a video without controls. A decorative video is hidden from screen readers, shows no controls, and shows its first frame unless video sets a playback.

#Video

video holds the playback settings for a video src: playback, controls, loop, muted, controlsList, showDuration, and showScrubTime. They follow the same rules as HtVideo. An image ignores them, so set them without checking the URL. Without video, a video shows native controls.

Set playback: "none" for a thumbnail inside a clickable card, so the card gets the click instead of the native controls.

Set playback: "scrub" for a grid of creatives that mixes images and videos, so a viewer can preview each video under the mouse.

#Loading and errors

showSkeleton, skeletonHeight, showError, onRetry, and loading work the same for an image and a video. See Loading and Error on the HtImage page. The error message names the kind of media that failed.

#Load events

onLoad fires when an image loads, or when a video has its first frame. onError fires when either fails to load.

A ref points at the <img> or the <video>. Check the element with instanceof before you read a property that only one has, such as complete on an image.

#Guidelines

#When to use

• Show media whose URL can be an image or a video, such as an uploaded creative asset or an image in a chat message.

#When not to use

• For a URL that is always an image — use HtImage instead.
• For a URL that is always a video — use HtVideo instead.

#Props

Inherits all style props, including color, border, and margin props.

Name	Default	Description
style	—	ChakraBoxProps["style"]Inline styles, merged with the surface-derived style.
alt	—	stringText alternative for the media. Required unless decorative is set.
decorative	—	trueMarks the media as decorative, so screen readers skip it.
showSkeleton	false	booleanShows a skeleton placeholder until the media loads.
skeletonHeight	"200px"	BoxProps["height"]Height of the skeleton placeholder.
showError	false	booleanReplaces the media with an error message if it fails to load. The message takes the media's size, border radius, and margin props.
onRetry	—	() => voidCalled from the Refresh button in the error message. The button shows only when showError is set and this prop is passed.
onLoad	—	BoxProps["onLoad"]Called when the media loads: when an image loads, or when a video has its first frame.
onError	—	BoxProps["onError"]Called when the media fails to load.
src	—	stringURL of the image or video. A URL that ends in a video extension (isVideoSrc) renders an HtVideo.
loading	—	HTMLImageElement["loading"]"lazy" defers loading until the image or video comes near the viewport.
video	{ playback: "click" }	MediaVideoPropsPlayback settings for a video src. An image ignores them. The keys are HtVideo props, with the same rules: playback ("click", "none", "autoplay", "hover", "scrub"), controls and loop (only autoplay), muted and controlsList (click and autoplay), showDuration (none, hover, scrub), and showScrubTime (only scrub). Use { playback: "none" } for a thumbnail inside a clickable card, and { playback: "scrub", showDuration: true } for a grid that mixes images and videos.