Image
Enhanced image component with shimmer loading skeleton, smooth fade-in transition, error fallback, and aspect ratio presets.
<arc-image> Overview
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="https://picsum.photos/600/400"
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="https://picsum.photos/200/200"
></arc-image>import { Image } from '@arclux/arc-ui-react';
export default function Example() {
return (
<>
<Image src="https://picsum.photos/600/400" 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="https://picsum.photos/600/400" 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="https://picsum.photos/600/400" 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="https://picsum.photos/600/400" 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="https://picsum.photos/600/400" 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="https://picsum.photos/600/400" 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.
-
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.
-
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.
-
fallbackstring'' - URL of a fallback image to display if the primary `src` fails to load.
Events
-
arc-load - Fired when the image successfully loads.
-
arc-error - Fired when the image fails to load.