Image
newPOV: your image shows up before JavaScript does. An image in a ratio box with loading and error layers, native srcset, sizes and picture sources.
Installation
Usage
<script setup lang="ts">
import { Image, ImageError, ImageLoading } from '@/components/ui/image'
</script>
<template>
<Image src="/photo.jpg" alt="A photo" :width="1200" :height="800">
<ImageLoading />
<ImageError />
</Image>
</template>
No resizing, no providers: src, srcset, sizes and sources take URLs you already have. The <img> renders on the server, so the image shows before hydration and even without JavaScript.
Examples
Size and ratio
The image fills a box. The box's ratio comes from, in order:
ratiowidthandheight- the file itself, once it loads (16 / 9 until then)
width and height are the file's size in pixels, like on <img>. They reserve space before the file arrives, so nothing jumps. width also sets the box's width, capped at its container; without it, the box fills its container.
Any other size is a class: w-64, or h-40 w-auto for a fixed height with the width following the ratio.
Fit and position
fit works like object-fit: cover (the default) fills and crops, contain shows everything, and fill, none and scale-down work as in CSS. position works like object-position, centred by default.



Loading
ImageLoading covers the image while it loads: a spinner by default, or your own content, like a skeleton or a tiny blurred copy. Add delay-300, so fast loads never flash it.
Images load lazily. Main character energy? For an image above the fold, set loading="eager" and fetchpriority="high".
src is undefined because the data is still on its way? The image keeps loading. null or '' means there's no image, and ImageError shows. In the demo, each fetch takes three seconds.
Errors
ImageError shows when the image fails, or when there's no src and no srcset: an icon by default, or your own content. Without it, you get the browser's broken image icon and the alt text.
Sources
sources wraps the image in a <picture>, one <source> per item, in order: newer formats with type, other crops with media. src stays as the fallback.

API Reference
Image
class is also accepted on every part and merged over its classes with tailwind-merge. Other attributes go on the box; style the <img> through it, for example class="[&_img]:grayscale".
| Prop | Default | Type and description |
|---|---|---|
| src | — | string | nullThe image URL, and the fallback when |
| alt | "" | stringText that replaces the image for screen readers. Empty by default, which marks the image decorative. |
| srcset | — | stringCandidate URLs with their widths or densities, as on |
| sizes | — | stringThe width the image takes at each breakpoint, as on |
| sources | — | ImageSource[]
|
| width | — | numberThe file's width in pixels. With |
| height | — | numberThe file's height in pixels. |
| ratio | — | numberThe box's width-to-height ratio, over |
| fit | "cover" | ImageFitHow the image fills its box, as |
| position | "50% 50%" | stringWhere the image sits in its box, as |
| loading | "lazy" | "lazy" | "eager"
|
| fetchpriority | — | "high" | "low" | "auto"The priority of the request relative to others, as on |
| decoding | — | "auto" | "sync" | "async"Whether to decode the image before showing it, as on |
| crossorigin | — | "" | "anonymous" | "use-credentials"Requests the image with CORS, as on |
| referrerpolicy | — | ReferrerPolicyThe referrer sent with the request, as on |
| draggable | undefined | booleanWhether the image can be dragged, as on |
| Event | Payload and description |
|---|---|
| load | [event: Event]Fires with the |
| error | [event: Event]Fires with the |
| Slot | Scope and description |
|---|---|
| default | {}Layers over the image, such as |
| Member | Type and description |
|---|---|
| imgEl | HTMLImageElement | nullThe |
ImageLoading
| Slot | Scope and description |
|---|---|
| default | {}What to show while loading, a spinner by default. |
ImageError
| Slot | Scope and description |
|---|---|
| default | {}What to show on error, an icon by default. |
class is also accepted on every part and merged over its classes with tailwind-merge. Other attributes go on the box; style the <img> through it, for example class="[&_img]:grayscale".
Props
- src
string | nullThe image URL, and the fallback whensourcesis set. While it isundefinedthe image counts as loading, for example until the data that holds it arrives;nullor an empty string, with nosrcset, means there is no image.- alt
"" stringText that replaces the image for screen readers. Empty by default, which marks the image decorative.- srcset
stringCandidate URLs with their widths or densities, as on<img>.- sizes
stringThe width the image takes at each breakpoint, as on<img>, to pick fromsrcset.- sources
ImageSource[]<source>elements for a<picture>around the image, in order:srcsetwithtype,media,sizes,widthandheight.- width
numberThe file's width in pixels. Withheight, sets the box's ratio before the file loads; also sets the box's width, capped at its container.- height
numberThe file's height in pixels.- ratio
numberThe box's width-to-height ratio, overwidthandheightand the file's own.- fit
"cover" ImageFitHow the image fills its box, asobject-fit.- position
"50% 50%" stringWhere the image sits in its box, asobject-position.- loading
"lazy" "lazy" | "eager"lazy(the default) waits until the image nears the viewport;eagerloads it at once.- fetchpriority
"high" | "low" | "auto"The priority of the request relative to others, as on<img>.- decoding
"auto" | "sync" | "async"Whether to decode the image before showing it, as on<img>.- crossorigin
"" | "anonymous" | "use-credentials"Requests the image with CORS, as on<img>.- referrerpolicy
ReferrerPolicyThe referrer sent with the request, as on<img>.- draggable
undefined booleanWhether the image can be dragged, as on<img>.
Emits
- load
[event: Event]Fires with theloadevent when the image has loaded, also when it had loaded before hydration.- error
[event: Event]Fires with theerrorevent when the image fails to load.
Slots
- default
{}Layers over the image, such asImageLoadingandImageError.
Exposed
- imgEl
HTMLImageElement | nullThe<img>element.
Slots
- default
{}What to show while loading, a spinner by default.
Slots
- default
{}What to show on error, an icon by default.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| image | data-state | The box. data-state is idle before hydration, then loading, loaded or error. |
| image-img | — | The <img>. |
| image-loading | — | The layer shown while loading. |
| image-error | — | The layer shown on error. |