Image

Component

View code

Show playground

Props

Usage

src

Sets the image source.

 <template>
    <Image src="/images/river.jpg" alt="River between mountains" />
</template>
 

• Type: string

alt

Sets the alternative text. Redundant wording such as "Image of" is removed with cleanImageAlt, since screen readers already announce an image.

 <template>
    <Image src="/images/river.jpg" alt="Image of a river between mountains" />
</template>
 

• Type: string
• Default: ''

caption

Sets the image caption. It is always shown in the lightbox, and on the page only when showCaption is on.

 <template>
    <Image src="/images/river.jpg" caption="River valley" />
</template>
 

• Type: string

showCaption

Shows the caption on the page, at the position set by captionPlacement.

 <template>
    <Image src="/images/river.jpg" caption="River valley" showCaption />
</template>
 

• Type: boolean
• Default: false

captionPlacement

Sets where the caption is displayed via the ImageCaptionPlacement enum.

 <template>
    <Image
        src="/images/river.jpg"
        caption="River valley"
        showCaption
        :captionPlacement="ImageCaptionPlacement.OVERLAY_BOTTOM"
    />
</template>
 

• Type: ImageCaptionPlacement
• Default: ImageCaptionPlacement.BELOW

Options

width

Sets the intrinsic width of the image. It helps the browser reserve space and avoid layout shifts.

 <template>
    <Image src="/images/river.jpg" :width="1200" :height="800" />
</template>
 

• Type: number

height

Sets the intrinsic height of the image. Use it together with width.

 <template>
    <Image src="/images/river.jpg" :width="1200" :height="800" />
</template>
 

• Type: number

aspectRatio

Crops the image to a fixed ratio via the AspectRatio enum. Without it, the image keeps its natural proportions.

 <template>
    <Image src="/images/river.jpg" :aspectRatio="AspectRatio.AR_16_9" />
</template>
 

• Type: AspectRatio

Options

fit

Sets how the image fills the box defined by aspectRatio via the ImageFit enum.

 <template>
    <Image
        src="/images/logo.png"
        :aspectRatio="AspectRatio.AR_1_1"
        :fit="ImageFit.CONTAIN"
    />
</template>
 

• Type: ImageFit
• Default: ImageFit.COVER

Options

hoverEffect

Sets the effect shown when you hover the image via the ImageHoverEffect enum.

 <template>
    <Image src="/images/river.jpg" :hoverEffect="ImageHoverEffect.GRAYSCALE" />
</template>
 

• Type: ImageHoverEffect
• Default: ImageHoverEffect.NONE

Options

hoverSplitDirection

Sets the direction in which the two chromatic layers separate with the SPLIT_ZOOM effect.

 <template>
    <Image
        src="/images/river.jpg"
        :hoverEffect="ImageHoverEffect.SPLIT_ZOOM"
        :hoverSplitDirection="ImageHoverSplitDirection.HORIZONTAL"
    />
</template>
 

• Type: ImageHoverSplitDirection
• Default: ImageHoverSplitDirection.DIAGONAL

Options

hasHoverIcon

Shows an icon in the center of the OVERLAY effect.

 <template>
    <Image
        src="/images/river.jpg"
        :hoverEffect="ImageHoverEffect.OVERLAY"
        :hasHoverIcon="false"
    />
</template>
 

• Type: boolean
• Default: true

hoverIcon

Sets the icon of the OVERLAY effect. By default it is a magnifier when useLightbox is on, and an eye otherwise.

 <template>
    <Image
        src="/images/river.jpg"
        :hoverEffect="ImageHoverEffect.OVERLAY"
        hoverIcon="mdi:heart"
    />
</template>
 

• Type: string

useLightbox

Opens the image in a Lightbox when you click it. The image becomes a button and the pointer shows a zoom cursor.

 <template>
    <Image src="/images/river.jpg" useLightbox />
</template>
 

• Type: boolean
• Default: false

lightboxSrc

Sets a larger source for the lightbox, so the thumbnail can stay light.

 <template>
    <Image
        src="/images/river-small.jpg"
        lightboxSrc="/images/river-large.jpg"
        useLightbox
    />
</template>
 

• Type: string

isClickable

Makes the image a button that emits click without opening a lightbox. It is always true when useLightbox is on.

 <template>
    <Image src="/images/river.jpg" isClickable @click="handleClick" />
</template>
 

• Type: boolean
• Default: false

useNuxtImg

Renders the image with NuxtImg from @nuxt/image instead of a plain img. It requires the @nuxt/image module in your app, and enables sizes and densities.

 <template>
    <Image src="/images/river.jpg" useNuxtImg />
</template>
 

• Type: boolean
• Default: false

sizes

Sets the sizes attribute passed to NuxtImg. It only applies with useNuxtImg.

 <template>
    <Image src="/images/river.jpg" useNuxtImg sizes="100vw md:50vw" />
</template>
 

• Type: string

densities

Sets the densities attribute passed to NuxtImg. It only applies with useNuxtImg.

 <template>
    <Image src="/images/river.jpg" useNuxtImg densities="x1 x2" />
</template>
 

• Type: string

loading

Sets how the browser loads the image via the ImageLoading enum. Use EAGER for images above the fold.

 <template>
    <Image src="/images/hero.jpg" :loading="ImageLoading.EAGER" />
</template>
 

• Type: ImageLoading
• Default: ImageLoading.LAZY

Options

containerClass

Adds custom classes to the root figure element.

 <template>
    <Image src="/images/river.jpg" containerClass="max-w-md" />
</template>
 

• Type: string

wrapperClass

Adds custom classes to the element that wraps the image, where the aspect ratio and rounded corners live.

 <template>
    <Image src="/images/river.jpg" wrapperClass="rounded-xl" />
</template>
 

• Type: string

imageClass

Adds custom classes to the img element.

 <template>
    <Image src="/images/river.jpg" imageClass="object-top" />
</template>
 

• Type: string

captionClass

Adds custom classes to the caption.

 <template>
    <Image src="/images/river.jpg" caption="River valley" showCaption captionClass="text-center" />
</template>
 

• Type: string

openAriaLabel

Sets the accessible name of the button when the image is clickable. Falls back to useDSConfig().lightbox.openImageText().

 <template>
    <Image src="/images/river.jpg" useLightbox openAriaLabel="Enlarge photo" />
</template>
 

• Type: string

Accessibility

Always provide an alt text, or leave it empty when the image is decorative. A clickable image is a native button, so it works with Enter and Space and shows a focus outline. The chromatic layers of SPLIT_ZOOM are hidden from assistive technology. Hover animations are disabled for users who prefer reduced motion.

Emits

Example

 <template>
    <Image src="/images/river.jpg" isClickable @click="handleClick" />
</template>
<script setup lang="ts">
const handleClick = () => {
    console.log('Image clicked')
}
</script>