<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
- Use arc-image for decorative background images — use CSS `background-image` instead
- Set `loading="eager"` on below-the-fold images — lazy is the default for a reason
- Omit `alt` text — the image is semantically meaningful content
- 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';
<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: `
<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" />
`,
})
export class GalleryComponent {}import { Image } from '@arclux/arc-ui-solid';
<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';
<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
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | '' | Image source URL. |
alt | string | '' | 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. |
fallback | string | '' | URL of a fallback image to display if the primary `src` fails to load. |
Events
| Event | Description |
|---|---|
arc-load | Fired when the image successfully loads. |
arc-error | Fired when the image fails to load. |