Image
A loading/error-aware image wrapper with skeleton placeholders, fallback sources, aspect-ratio boxes, and an optional caption.
Sunrise over the mountains
API
All inputs and configuration options for zyra-image.
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | required | Image URL |
alt | string | '' | Accessible alt text, also shown under the fallback icon on error |
fallbackSrc | string | '' | Second URL to try if src fails to load, before showing the placeholder |
ratio | number | string | null | null | Locks a fixed aspect ratio (e.g. "16/9", "1/1"); null sizes to the image itself |
objectFit | 'cover' | 'contain' | 'fill' | 'none' | 'scale-down' | 'cover' | CSS object-fit applied to the image |
radius | 'none' | 'sm' | 'md' | 'lg' | 'full' | 'none' | Corner rounding |
loading | 'lazy' | 'eager' | 'lazy' | Native img loading attribute |
caption | string | '' | Optional caption rendered below the image |
loaded (output) | void | - | Emits once the image has finished loading successfully |
error (output) | void | - | Emits when the image (and fallbackSrc, if any) both fail to load |
Tokens
CSS custom properties zyra-image reads at runtime — override any of these in your own stylesheet after @use 'zyra-ng-ui'; to restyle it without touching the component itself.
| Token | Default points to | Description |
|---|---|---|
Placeholder background--zyra-color-image-placeholder-bg | var(--zyra-color-surface-inset) | Background of the box while loading and behind the fallback icon. |
Placeholder icon--zyra-color-image-placeholder-icon | var(--zyra-color-foreground-subtle) | Color of the broken-image icon shown on error. |
Caption text--zyra-color-image-caption-text | var(--zyra-color-foreground-subtle) | Color of the caption text and the fallback label under the icon. |
Accessibility
Built to meet WCAG 2.0 AA. These notes cover the key ARIA, keyboard, and interaction behaviours.
- alt is applied to the underlying <img>, and reused as the label under the fallback icon on error
- The fallback placeholder uses role="img" with an aria-label so screen readers still get a description when the image fails
- The loading skeleton is purely decorative and does not interfere with the accessibility tree