Image

new

POV: your image shows up before JavaScript does. An image in a ratio box with loading and error layers, native srcset, sizes and picture sources.

Demo
A river running over stones below a forested mountain

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:

  1. ratio
  2. width and height
  3. 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.

Fit
The gilded nave of a baroque church
cover
The gilded nave of a baroque church
contain
The gilded nave of a baroque church
cover, top

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".

Placeholder
A ladybird opening its wings on a flower bud
A ladybird opening its wings on a flower bud
A ladybird opening its wings on a flower bud

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.

Deferred
A ladybird opening its wings on a flower bud

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.

Fallback
A photo that no longer exists

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.

Sources
A river running over stones below a forested mountain

API Reference

Data attributes

data-slotAttributesDescription
imagedata-stateThe 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.

Changelog

  1. registry 0.24.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  2. core 0.17.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  3. registry 0.8.0

    686b10b — ImageLoading and ImageError leave the render tree (display: none) while their state is not showing, so the default Spinner stops animating behind loaded images. The fade still plays through transition-behavior: allow-discrete and @starting-style, and a display class passed to a layer still wins while it is shown.

  4. registry 0.6.0

    aa71d8d — Avatar: Avatar, AvatarImage, AvatarFallback, AvatarGroup and AvatarGroupCount. Five sizes from 24 to 64px; a group overlaps its members by a quarter of their size and rings them in --avatar-ring; Image goes in an avatar in place of AvatarImage for sources and layers.

  5. registry 0.4.0

    c0d0a59 — Add Image, with ImageLoading and ImageError: an image in a ratio box with fit and position, native srcset, sizes and <picture> sources, lazy loading by default, and load and error tracking that holds across SSR hydration. It shows its loading layer while src is undefined and its error layer when src is null. The API follows Nuxt Image and Quasar's QImg, without providers.