ki-image
@kimen/elements/ki-image- Source
- Agent reference
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.
<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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
alt | alt | string | undefined | – | Describe what the image shows for the task at hand. Required and nonblank for an informative image. Omit it for a decorative image. |
decorative | decorative | boolean | false | Hide the media from assistive technology when it conveys no information. |
fallback-label | fallbackLabel | string | 'Image unavailable' | Localizable fallback label. An informative fallback appends the image's description, when available, to this label. |
fit | fit | "contain" | "cover" | 'cover' | Cover fills the frame. Contain preserves the whole image in it. |
loading | loading | "eager" | "lazy" | 'lazy' | Native loading hint. Use eager for a critical image above the fold. |
radius | radius | "lg" | "md" | "none" | 'lg' | Corner radius of the media frame. |
ratio | ratio | "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. |
src | src | string | – | Relative or HTTP(S) image URL. Refused sources are left unloaded. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-error | CustomEvent<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
| Slot | Description |
|---|---|
caption | Optional visible context displayed below the media in a figcaption. |
CSS parts
| Part | Description |
|---|---|
caption | The figcaption carrying the slotted caption. |
fallback | The unavailable-image indicator inside the frame. |
figure | The figure containing the frame and optional caption. |
frame | The reserved media box and its shape and backing surface. |
image | The 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.
| Token | Description |
|---|---|
--ki-image-caption-fg | Text colour of the visible caption. |
--ki-image-caption-font-family | Typeface of the visible caption. |
--ki-image-caption-font-size | Type size of the visible caption. |
--ki-image-caption-gap | Space between the image frame and its caption. |
--ki-image-caption-line-height | Line height of the visible caption. |
--ki-image-fallback-backdrop-filter | Complete filter applied behind the media surface. |
--ki-image-fallback-bg | Solid fill behind the image and fallback symbol. |
--ki-image-fallback-bg-image | Optional background image over the media fill. |
--ki-image-fallback-fg | Foreground of the fallback symbol. |
--ki-image-fallback-icon-size | Inline and block size of the unavailable-image symbol. |
--ki-image-fallback-icon-stroke-width | Stroke width of the unavailable-image symbol. |
--ki-image-radius | Corner radius of the default media frame. |
--ki-image-radius-md | Corner radius of the medium media frame. |
--ki-typography-family-body | semantic font family for typography family body. |