Image
Enhanced image component with shimmer loading skeleton, smooth fade-in transition, error fallback, and aspect ratio presets.
<arc-image>Overview
Image wraps the native <img> element with loading states and error handling that would otherwise require custom boilerplate in every project. While the image loads, a shimmer skeleton animation fills the container, giving users immediate visual feedback. Once loaded, the image fades in smoothly via a CSS opacity transition.
If the image fails to load, the component switches to an error state that displays either a custom fallback image (via the fallback prop) or a default placeholder icon. This three-state lifecycle (loading, loaded, error) is automatic and requires no imperative code.
Six aspect ratio presets (1/1, 4/3, 16/9, 21/9, 3/4, 9/16) constrain the container dimensions before the image loads, preventing layout shift. The fit property maps directly to CSS object-fit, defaulting to cover for full-bleed cropping. Native lazy loading is enabled by default via the loading="lazy" attribute.
Guidelines
When to use
- Always provide meaningful `alt` text for accessibility
- Set an `aspect` ratio to prevent layout shift during loading
- Use `fit="contain"` for logos or icons that should not be cropped
- Provide a `fallback` image URL for critical images that must always display something
When not to use
- Do not use arc-image for decorative background images. Use CSS `background-image` instead
- Do not set `loading="eager"` on below-the-fold images. Lazy is the default for a reason
- Do not omit `alt` text. The image is semantically meaningful content
- Do not use extremely large source images without server-side resizing
Features
- Shimmer skeleton animation during image loading
- Smooth opacity fade-in transition when the image loads
- Automatic error fallback with placeholder icon or custom fallback image
- Six aspect ratio presets to prevent layout shift: 1/1, 4/3, 16/9, 21/9, 3/4, 9/16
- Five object-fit modes: cover (default), contain, fill, none, scale-down
- Native lazy loading enabled by default
- Respects `prefers-reduced-motion`: disables shimmer and fade when set
- Exposed CSS parts: wrapper, image, fallback
Preview
Usage
This component requires JavaScript. No pure HTML/CSS version is available. Use the Web Component directly or a framework wrapper.
<arc-image
src="/demo/mountain-600x400.jpg"
alt="Mountain landscape"
aspect="16/9"
></arc-image>
<!-- With fallback -->
<arc-image
src="https://example.com/missing.jpg"
alt="Product photo"
aspect="1/1"
fallback="/demo/fallback-200x200.jpg"
></arc-image>import { Image } from '@arclux/arc-ui-react';
export default function Example() {
return (
<>
<Image src="/demo/mountain-600x400.jpg" alt="Mountain landscape" aspect="16/9" />
<Image src="/missing.jpg" alt="Product" aspect="1/1" fallback="/placeholder.png" />
</>
);
}<script setup>
import { Image } from '@arclux/arc-ui-vue';
</script>
<template>
<Image src="/demo/mountain-600x400.jpg" alt="Mountain landscape" aspect="16/9" />
<Image src="/missing.jpg" alt="Product" aspect="1/1" fallback="/placeholder.png" />
</template><script>
import { Image } from '@arclux/arc-ui-svelte';
</script>
<Image src="/demo/mountain-600x400.jpg" alt="Mountain landscape" aspect="16/9" />
<Image src="/missing.jpg" alt="Product" aspect="1/1" fallback="/placeholder.png" />import { Component } from '@angular/core';
import { Image } from '@arclux/arc-ui-angular';
@Component({
imports: [Image],
template: `
<arc-image src="/demo/mountain-600x400.jpg" alt="Mountain landscape" aspect="16/9" />
<arc-image src="/missing.jpg" alt="Product" aspect="1/1" fallback="/placeholder.png" />
`,
})
export class GalleryComponent {}import { Image } from '@arclux/arc-ui-solid';
export default function Example() {
return (
<>
<Image src="/demo/mountain-600x400.jpg" alt="Mountain landscape" aspect="16/9" />
<Image src="/missing.jpg" alt="Product" aspect="1/1" fallback="/placeholder.png" />
</>
);
}import { Image } from '@arclux/arc-ui-preact';
export default function Example() {
return (
<>
<Image src="/demo/mountain-600x400.jpg" alt="Mountain landscape" aspect="16/9" />
<Image src="/missing.jpg" alt="Product" aspect="1/1" fallback="/placeholder.png" />
</>
);
}API
srcstring''- Image source URL.
altstring''- Alt text for the image. Used as the accessible description.
fallbackstring''- URL of a fallback image to display if the primary
srcfails to load. aspect'' | '1/1' | '4/3' | '16/9' | '21/9' | '3/4' | '9/16'''- Constrains the container to a fixed aspect ratio, preventing layout shift during loading. Empty (the default) leaves the container unconstrained; an unrecognised ratio falls back to it.
fit'cover' | 'contain' | 'fill' | 'none' | 'scale-down''cover'- CSS object-fit mode controlling how the image fills its container.
loading'lazy' | 'eager''lazy'- Native loading strategy. Lazy defers off-screen images until they approach the viewport.
Events
arc-load- Fired when the image successfully loads.
arc-error- Fired when the image fails to load.