Skip to content
Kimenpre-v1documentation home
Color scheme

ki-image

Use ki-image for one image with a predictable crop or a fallback. Give an informative image an alt description of the details that matter on this page. Use the caption slot for supporting context or attribution.

Theme for this example
Color scheme for this example
View from the ridge
<ki-image src="/docs/_astro/hills.DVAngwG1.svg" alt="Low green hills under a pale sky" ratio="16:9">
<span slot="caption">View from the ridge</span>
</ki-image>

An explicit ratio keeps the frame the same size while the image loads or when it falls back. auto reserves 16:9 until the source supplies its natural ratio. fit="contain" keeps the entire image visible in a fixed frame. Loading is lazy by default. Use loading="eager" for an image that must load immediately.

Fallback and accessibility

An unavailable or refused source shows a fallback in the same frame. The accessible name includes the alt, for example Image unavailable: Office floor plan. Use fallback-label to translate the prefix. A missing or blank alt on an informative image shows the fallback before the source is requested.

Use decorative for imagery that adds no information. Assistive technology skips decorative images and their fallback, while an authored caption stays available. The image frame stays out of sequential keyboard navigation.

src accepts HTTP(S) and relative references. The guarded catalog also applies any configured origin allowlist before rendering. ki-error signals a failed image load or URL refusal.

API reference

When to use: to show a photo, illustration, or diagram with a predictable layout. Supply task-relevant alt text, or mark purely decorative media as decorative. Set an explicit ratio when the layout must stay fixed.

When not to use: for a background decoration, a video, or an interactive control. Use a separate control to open or otherwise act on an image.

Properties & attributes

AttributePropertyTypeDefaultDescription
altaltstring | undefined–Describe what the image shows for the task at hand. Required and nonblank for an informative image. Omit it for a decorative image.
decorativedecorativebooleanfalseHide the media from assistive technology when it conveys no information.
fallback-labelfallbackLabelstring'Image unavailable'Localizable fallback label. An informative fallback appends the image's description, when available, to this label.
fitfit"contain" | "cover"'cover'Cover fills the frame. Contain preserves the whole image in it.
loadingloading"eager" | "lazy"'lazy'Native loading hint. Use eager for a critical image above the fold.
radiusradius"lg" | "md" | "none"'lg'Corner radius of the media frame.
ratioratio"16:9" | "1:1" | "3:2" | "4:3" | "auto"'auto'An explicit ratio reserves the same frame before load and on failure. Auto reserves 16:9 first and uses the intrinsic ratio after load.
srcsrcstring–Relative or HTTP(S) image URL. Refused sources are left unloaded.

Events

EventDetail typeDescription
ki-errorCustomEvent<void>Reports a load failure or rejected URL once per source attempt. Bubbles and crosses shadow boundaries so consumers can observe it on a surface.

Slots

SlotDescription
captionOptional visible context displayed below the media in a figcaption.

CSS parts

PartDescription
captionThe figcaption carrying the slotted caption.
fallbackThe unavailable-image indicator inside the frame.
figureThe figure containing the frame and optional caption.
frameThe reserved media box and its shape and backing surface.
imageThe native image and its fit within the frame.

CSS custom properties

The public styling contract of ki-image: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-image-caption-fgText colour of the visible caption.
--ki-image-caption-font-familyTypeface of the visible caption.
--ki-image-caption-font-sizeType size of the visible caption.
--ki-image-caption-gapSpace between the image frame and its caption.
--ki-image-caption-line-heightLine height of the visible caption.
--ki-image-fallback-backdrop-filterComplete filter applied behind the media surface.
--ki-image-fallback-bgSolid fill behind the image and fallback symbol.
--ki-image-fallback-bg-imageOptional background image over the media fill.
--ki-image-fallback-fgForeground of the fallback symbol.
--ki-image-fallback-icon-sizeInline and block size of the unavailable-image symbol.
--ki-image-fallback-icon-stroke-widthStroke width of the unavailable-image symbol.
--ki-image-radiusCorner radius of the default media frame.
--ki-image-radius-mdCorner radius of the medium media frame.
--ki-typography-family-bodysemantic font family for typography family body.

Workshop

Open ki-image in Storybook