HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
ImageView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorAn image that shows a placeholder while it loads and a fallback if it fails.StableSince 0.1.0MediaUsageimport'@fusion.dev/helix/image'import'@fusion.dev/helix-headless/image'Preview
API ReferenceRoothelix-imageAn image that shows a placeholder while it loads and a fallback if it fails.
PropTypeDescriptionaltstringA text description of the image, read by screen readers.crossOrigin"anonymous"|"use-credentials"|nullDefaultnullHow the image is fetched across origins. It decides whether a canvas can
read the image.decoding"async"|"auto"|"sync"Default"async"Whether the browser may decode the image off the main thread.fetchPriority"auto"|"high"|"low"Default"auto"How urgently the browser fetches the image. Set high on the main image
of a page.loading"eager"|"lazy"Whether the image waits to load until it is nearly on screen. Defaults to
lazy.placeholderDelaynumberDefault0How long, in milliseconds, the placeholder waits before it shows. The
attribute also takes a CSS time, such as 300ms.referrerPolicystringDefault""How much of the referring URL to send with the request.shape"rounded"The shape of the corners. rounded rounds them.sizesstringDefault""The width the image takes in the layout, passed through to the inner image.srcstringDefault""The URL of the image.srcsetstringDefault""The candidate files and their widths, passed through to the inner image.status"error"|"loaded"|"loading"Default"loading"The loading state: loading, loaded, or error.
ReadTypeDescriptioncompletebooleanWhether the image has finished loading, successfully or not.currentSrcstringThe candidate the browser chose from srcset.naturalHeightnumberThe image's intrinsic height in pixels. Zero until the image loads.naturalWidthnumberThe image's intrinsic width in pixels. Zero until the image loads.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptionfallbackShown in place of the image if it fails to load, and read by screen readers then, such as "Photo unavailable".placeholderShown until the image loads.
EventTypeDescriptionerrorEventThe image failed to load. Relayed from the inner image, whose own event stays inside the shadow root.loadEventThe image loaded. Relayed from the inner image, whose own event stays inside the shadow root.
PartDescriptionfallbackThe fallback, shown when the image fails to load.imageThe image itself.placeholderThe placeholder, shown until the image loads.
CSS PropertyDescription--image-aspectThe aspect ratio of the box, such as 16 / 9.--image-fade-durationHow long the picture takes to fade in once it loads. 0s shows it at once.--image-fallback-background-colorThe background behind the fallback. Defaults to the placeholder's.--image-fallback-colorThe color of the fallback's text.--image-fitHow the image fills the box, as an object-fit value.--image-placeholder-colorThe background behind the placeholder and the fallback.--image-positionWhich part of the image stays in view when it is cropped, as an object-position value.--image-radiusThe corner radius when shape is rounded.
Custom stateDescriptionerrorThe image failed to load, and the fallback shows.loadedThe image loaded.loadingThe image is on its way, so neither loaded nor error is true yet.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.waitingThe image is on its way and placeholder-delay still holds the placeholder back.
Roothelix-headless-imageAn image that shows a placeholder while it loads and a fallback if it fails.
PropTypeDescriptionaltstringA text description of the image, read by screen readers.crossOrigin"anonymous"|"use-credentials"|nullDefaultnullHow the image is fetched across origins. It decides whether a canvas can
read the image.decoding"async"|"auto"|"sync"Default"async"Whether the browser may decode the image off the main thread.fetchPriority"auto"|"high"|"low"Default"auto"How urgently the browser fetches the image. Set high on the main image
of a page.loading"eager"|"lazy"Whether the image waits to load until it is nearly on screen. Defaults to
lazy.placeholderDelaynumberDefault0How long, in milliseconds, the placeholder waits before it shows. The
attribute also takes a CSS time, such as 300ms.referrerPolicystringDefault""How much of the referring URL to send with the request.sizesstringDefault""The width the image takes in the layout, passed through to the inner image.srcstringDefault""The URL of the image.srcsetstringDefault""The candidate files and their widths, passed through to the inner image.status"error"|"loaded"|"loading"Default"loading"The loading state: loading, loaded, or error.
ReadTypeDescriptioncompletebooleanWhether the image has finished loading, successfully or not.currentSrcstringThe candidate the browser chose from srcset.naturalHeightnumberThe image's intrinsic height in pixels. Zero until the image loads.naturalWidthnumberThe image's intrinsic width in pixels. Zero until the image loads.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptionfallbackShown in place of the image if it fails to load, and read by screen readers then, such as "Photo unavailable".placeholderShown until the image loads.
EventTypeDescriptionerrorEventThe image failed to load. Relayed from the inner image, whose own event stays inside the shadow root.loadEventThe image loaded. Relayed from the inner image, whose own event stays inside the shadow root.
PartDescriptionfallbackThe fallback, shown when the image fails to load.imageThe image itself.placeholderThe placeholder, shown until the image loads.
Custom stateDescriptionerrorThe image failed to load, and the fallback shows.loadedThe image loaded.loadingThe image is on its way, so neither loaded nor error is true yet.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.waitingThe image is on its way and placeholder-delay still holds the placeholder back.
Examples
NameDescriptionEventsThe load and error events, under their native names.FallbackAn image that fails to load, with a fallback in its place.PlaceholderA placeholder shown while the image loads, or before it has a source.PreviewAn image with a fixed aspect ratio and rounded corners.PreviewAn image with a fixed aspect ratio and rounded corners.ResponsiveCandidate widths for the browser to choose from, and a high fetch priority for the main image.