Image

Enhanced image component with loading skeleton, error fallback, lightbox preview, captions, and lazy loading.

<script setup lang="ts">
import { VxImage } from 'veloxui'
</script>

<template>
  <VxImage src="https://picsum.photos/300/200" alt="Mountain" :width="280" :height="180" :radius="8" />
</template>

Object Fit

Control how the image fills its container with the fit prop.

cover

contain

fill

none

scale-down

<template>
  <VxImage src="..." fit="cover" />
  <VxImage src="..." fit="contain" />
  <VxImage src="..." fit="fill" />
  <VxImage src="..." fit="none" />
  <VxImage src="..." fit="scale-down" />
</template>

Preview (Lightbox)

Enable preview to allow clicking the image to open a full-screen lightbox. Press Escape or click outside to close.

New York City at sunset

<script setup lang="ts">
import { VxImage } from 'veloxui'
</script>

<template>
  <!-- Click to open lightbox -->
  <VxImage src="https://picsum.photos/800/500" preview />

  <!-- With caption in lightbox -->
  <VxImage src="..." preview caption="New York City at sunset" />
</template>

Caption

A peaceful mountain lake

Photo by VeloxUI Team

<template>
  <!-- String caption -->
  <VxImage src="..." caption="A peaceful mountain lake" />

  <!-- Custom caption slot -->
  <VxImage src="...">
    <template #caption>
      <span>Photo by <strong>VeloxUI Team</strong></span>
    </template>
  </VxImage>
</template>

Border Radius

<template>
  <VxImage src="..." :radius="0" />     <!-- sharp -->
  <VxImage src="..." :radius="8" />     <!-- rounded -->
  <VxImage src="..." :radius="16" />    <!-- more rounded -->
  <VxImage src="..." radius="50%" />    <!-- circle -->
</template>

Error Fallback

When the image fails to load, shows a placeholder. Provide a fallback URL for an alternative image, or use the error slot for custom content.

Default error

Fallback image

Custom error slot

<template>
  <!-- Default error state -->
  <VxImage src="https://broken.url" />

  <!-- Fallback image -->
  <VxImage src="https://broken.url" fallback="https://picsum.photos/200/140" />

  <!-- Custom error slot -->
  <VxImage src="https://broken.url">
    <template #error>
      <div>Image unavailable</div>
    </template>
  </VxImage>
</template>

Lazy Loading

Add lazy to defer loading until the image enters the viewport. Uses native loading="lazy".

<template>
  <VxImage src="https://picsum.photos/800/500" lazy />
</template>

Srcset & Sizes

Provide responsive sources for retina and different viewport sizes.

<template>
  <VxImage
    src="photo-400.jpg"
    srcset="photo-400.jpg 400w, photo-800.jpg 800w, photo-1200.jpg 1200w"
    sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
  />
</template>

Props

Prop	Type	Default	Description
src	string	''	Image source URL
alt	string	''	Alt text
width	number | string	—	Image width
height	number | string	—	Image height
fit	'cover' | 'contain' | 'fill' | 'none' | 'scale-down'	'cover'	Object-fit mode
lazy	boolean	false	Native lazy loading
preview	boolean	false	Enable lightbox on click
fallback	string	''	Fallback image URL on error
radius	number | string	0	Border radius
srcset	string	''	Responsive srcset
sizes	string	''	Responsive sizes
caption	string	''	Caption text below image

Events

Event	Type	Description
load	(event)	Image loaded successfully
error	(event)	Image failed to load
close	()	Preview lightbox closed

Slots

Slot	Description
error	Custom error state content
caption	Custom caption content

---

ImageViewer

Full-screen image viewer with zoom, rotate, flip, pan, keyboard navigation, thumbnails, and gallery support.

Gallery

Click any image to open the viewer. Use arrow keys, mouse wheel to zoom, and drag to pan.

<script setup lang="ts">
import { ref } from 'vue'
import { VxImage, VxImageViewer } from 'veloxui'

const viewerOpen = ref(false)
const viewerIdx = ref(0)

const gallery = [
  { src: 'https://picsum.photos/800/600?10', caption: 'Mountain sunrise' },
  { src: 'https://picsum.photos/800/600?11', caption: 'Ocean waves' },
  { src: 'https://picsum.photos/800/600?12', caption: 'Forest trail' },
  { src: 'https://picsum.photos/800/600?13', caption: 'City skyline' },
  { src: 'https://picsum.photos/800/600?14', caption: 'Desert dunes' },
]

function openAt(i: number) {
  viewerIdx.value = i
  viewerOpen.value = true
}
</script>

<template>
  <VxImage v-for="(img, i) in gallery" :key="i" :src="img.src"
    :width="120" :height="90" :radius="8"
    @click="openAt(i)" style="cursor: pointer;" />

  <VxImageViewer
    v-model="viewerOpen"
    :images="gallery"
    :initial-index="viewerIdx"
    show-thumbnails
  />
</template>

Simple (String Array)

Pass an array of URL strings for quick usage.

<script setup lang="ts">
import { ref } from 'vue'
import { VxImageViewer, VxButton } from 'veloxui'

const open = ref(false)
</script>

<template>
  <VxButton @click="open = true">Open Viewer</VxButton>

  <VxImageViewer
    v-model="open"
    :images="[
      'https://picsum.photos/800/600?20',
      'https://picsum.photos/800/600?21',
      'https://picsum.photos/800/600?22',
    ]"
  />
</template>

With Thumbnails

<template>
  <VxImageViewer :images="gallery" show-thumbnails />
</template>

Keyboard Shortcuts

Key	Action
←	Previous image
→	Next image
+ / =	Zoom in
-	Zoom out
R	Rotate right 90deg
0	Reset (fit to screen)
Esc	Close viewer

Toolbar Actions

The toolbar includes: zoom out, zoom percentage, zoom in, rotate left, rotate right, flip horizontal, flip vertical, reset to fit.

Mouse wheel zooms in/out. When zoomed past 100%, click and drag to pan the image.

ImageViewer Props

Prop	Type	Default	Description
images	(string | ImageViewerItem)[]	[]	Array of image URLs or objects
modelValue	boolean	false	Show/hide viewer (v-model)
initialIndex	number	0	Starting image index
zoomStep	number	0.25	Zoom increment per step
minZoom	number	0.5	Minimum zoom level
maxZoom	number	5	Maximum zoom level
loop	boolean	true	Loop navigation at ends
showToolbar	boolean	true	Show bottom toolbar
showCounter	boolean	true	Show "1 / 5" counter
showThumbnails	boolean	false	Show thumbnail strip

ImageViewer Events

Event	Type	Description
update:modelValue	(boolean)	Viewer opened/closed
change	(index: number)	Active image changed
close	()	Viewer closed

ImageViewerItem Interface

interface ImageViewerItem {
  src: string
  alt?: string
  caption?: string
}

Exposed Methods

Method	Description
prev()	Go to previous image
next()	Go to next image
goTo(index)	Jump to specific image
zoomIn()	Zoom in by zoomStep
zoomOut()	Zoom out by zoomStep
rotateLeft()	Rotate 90deg counter-clockwise
rotateRight()	Rotate 90deg clockwise
reset()	Reset zoom, rotation, flip, pan
close()	Close the viewer