PhotoCarousel

Render a horizontal photo carousel with controls, thumbnails, and optional autoplay or lightbox behavior.

PhotoCarousel provides one slide per snap. Its lightbox is off by default.

Minimal usage

app/pages/carousel.vue

<script setup lang="ts">
import type { PhotoItem } from '@lupinum/nuxt-photo/app'

const photos: PhotoItem[] = [
  { id: 'one', src: '/photos/one.jpg', width: 1200, height: 800, alt: 'Rocky coast' },
  { id: 'two', src: '/photos/two.jpg', width: 1200, height: 800, alt: 'Calm sea' },
]
</script>

<template>
  <PhotoCarousel :photos="photos" />
</template>

Props

Prop	Type	Default	Description
`photos`	`readonly PhotoItem[]`	-	Required. Ordered slides.
`validation`	`'throw' \| 'drop'`	`'throw'`	Invalid collection policy.
`imageAdapter`	`ImageAdapter`	provided/module default	Override image delivery for this carousel.
`loop`	`boolean`	`false`	Continue from the final slide to the first.
`dragFree`	`boolean`	`false`	Allow the track to stop between snap points.
`direction`	`'ltr' \| 'rtl'`	inherited	Set carousel and thumbnail direction.
`showArrows`	`boolean`	`true`	Render previous and next buttons.
`showThumbnails`	`boolean`	`true`	Render the thumbnail rail.
`showCounter`	`boolean`	`true`	Render the current slide counter.
`showDots`	`boolean`	`false`	Render slide dots.
`autoplay`	`boolean \| PhotoCarouselAutoplayOptions`	`false`	Enable autoplay.
`slideSize`	`string`	-	CSS `flex-basis` for each slide.
`slideAspect`	`string`	-	CSS `aspect-ratio` for each slide.
`gap`	`string`	-	CSS gap between slides.
`thumbSize`	`string`	-	Thumbnail width.
`lightbox`	`boolean \| Component`	`false`	Enable or replace the optional lightbox.
`transition`	`LightboxTransitionOption`	`'auto'`	Optional lightbox transition configuration.
`slideClass`	`string`	-	Classes for each slide.
`imgClass`	`string`	-	Classes for each main image.
`thumbClass`	`string`	-	Classes for each thumbnail.
`captionClass`	`string`	-	Classes for the caption.
`controlsClass`	`string`	-	Classes for the controls wrapper.

Events

Event	Payload	When it fires
`invalidPhotos`	`InvalidPhotosEvent`	Invalid entries are found while `validation="drop"` is set.

vue

<PhotoCarousel :photos="photos" validation="drop" @invalid-photos="reportInvalidPhotos" />

Slots

Slot	Props	Purpose
`slide`	`{ photo, index, selected, open }`	Replace each main slide.
`thumb`	`{ photo, index, selected, goTo }`	Replace each thumbnail.
`caption`	`{ photo, index, count }`	Replace the caption.
`controls`	`{ goToPrev, goToNext, canGoToPrev, canGoToNext, selectedIndex, snapCount, goTo }`	Replace the complete control block.
`prev`	-	Replace the previous-button content.
`next`	-	Replace the next-button content.
`dots`	`{ snaps, selectedIndex, goTo }`	Replace the dot indicators.

Custom slide and thumb slots replace adapter-backed image content. Render PhotoImage inside the slot to keep the configured adapter.

Exposed template-ref API

PhotoCarousel exposes no public template-ref controller. Use the controls slot callbacks for custom carousel controls.

Important behavior

The carousel uses documented Embla behavior internally, with one slide per snap.
loop, dragFree, direction, visual options, and autoplay are reactive.
When direction is omitted, inherited direction is resolved at mount. Bind direction when locale direction can change while the component remains mounted.
Main and thumbnail rails use the same direction.
lightbox is setup-time. Remount with a new key to add, remove, or replace it.
Arrow, thumbnail, and dot buttons use the configured localization labels.

Autoplay options

interface PhotoCarouselAutoplayOptions {
  delayMs?: number
  stopOnInteraction?: boolean
  stopOnMouseEnter?: boolean
}

delayMs defaults to 4000, stopOnInteraction to true, and stopOnMouseEnter to false. delayMs must be a positive finite number.

vue

<PhotoCarousel
  :photos="photos"
  loop
  :autoplay="{
    delayMs: 5000,
    stopOnInteraction: false,
    stopOnMouseEnter: true,
  }"
/>

Build a carousel covers practical setup. Lightbox, gestures, and accessibility lists keyboard and reduced-motion behavior.