HtImage

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

#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 an image 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.

#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.

#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.
• For a URL that is always a video — use HtVideo instead.
• For a URL that can be an image or a video, such as an uploaded creative asset — use HtMedia instead. HtImage renders only <img>.

#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.
• decorative accepts only true. Narrow a boolean before you pass it, and pass decorative rather than alt="", so the same props work on HtMedia when the URL is a video.

#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.
loading	—	HTMLImageElement["loading"]Native image loading strategy. Set "lazy" to defer offscreen images.
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.