HtImage

Image that requires a text alternative or an explicit decorative flag, with an optional loading skeleton, an optional error message, and video playback for video sources.

#Example

#Usage

#Decorative

HtImage requires either alt or decorative. Set decorative when the image adds no information, such as an illustration next to a heading that already says the same thing. It renders an empty alt, so screen readers skip it.

#Loading

Set showSkeleton when the image loads slowly and the space around it must not jump. A skeleton fills the slot until the image loads, then the image fades in. Set skeletonHeight to match the expected image height. This demo image takes a few seconds to load.

If the image fails to load, the skeleton goes away and onError fires. Set loading="lazy" to defer images below the fold until the user scrolls near them.

#Error

Set showError to replace media that fails to load with an error message, instead of the browser's broken-image icon. The message takes the image's size, border radius, and margin props. Pass onRetry to add a Refresh button, for example to request a new signed URL.

Do not set showError on small images, such as logos and icons. The message does not fit. Use onError to render a fallback, such as an Avatar, instead.

#Video sources

When src ends in .mp4, .mov, .webm, .avi, or .mkv, HtImage renders a <video> with inline playback and native controls. Set disableVideoControls to hide the controls. Use the exported isVideoSrc helper to branch other UI on the same check.

#Wrapping HtImage

HtImageProps is a union, so a plain Omit makes alt and decorative both optional and drops the check. Derive a wrapper's props with a distributive Omit to keep it.

#Guidelines

#When to use

• Show a raster or SVG image from a URL, such as a logo, a product photo, or an empty-state illustration.
• Show media whose URL can be an image or a video, such as an uploaded creative asset. Branch other UI on the same check with isVideoSrc.

#When not to use

• For a user or workspace avatar — use Avatar instead.
• For an icon — import its *Icon component from @hightouch/htui, such as AudienceIcon, instead of an image file. Pass it to the host component's icon prop, or render it inline. The Icons page shows the full set.
• For a background image behind content — set bgImage on a Box.

#Accessibility

• Write alt text that says what the image shows in the context of the page. Do not start it with "Image of".
• decorative and alt are mutually exclusive, so every call site makes an explicit choice.
• For a video source, alt becomes the video's aria-label.
• decorative accepts only true. Narrow a boolean before you pass it, or pass alt="" for the decorative case.

#Props

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

Name	Default	Description
surface	—	SurfaceExplicitly set the surface theme advertised to descendant form elements. Useful when bg is a value the surface resolver doesn't recognise – e.g. responsive object syntax, an arbitrary hex, or a token applied via sx instead of bg.
style	—	ChakraBoxProps["style"]Inline styles, merged with the surface-derived style.
src	—	stringURL of the image or video. A URL that ends in a video extension renders a <video>.
loading	—	HTMLImageElement["loading"]Native image loading strategy. Set "lazy" to defer offscreen images.
alt	—	stringText alternative for the image. Required unless decorative is set.
decorative	—	trueMarks the image as decorative, so it renders with an empty alt and screen readers skip it.
disableVideoControls	false	booleanHides the native controls when src is a video.
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 image loads, or when a video has its first frame.
onError	—	BoxProps["onError"]Called when the image or video fails to load.