Types

The canonical source for the commonly used types below is @lupinum/vue-photo. Nuxt apps import app-facing types from @lupinum/nuxt-photo/app; plain Vue apps import them from @lupinum/vue-photo.

import type {
  PhotoItem,
  AlbumLayout,
  RowsAlbumLayout,
  ColumnsAlbumLayout,
  MasonryAlbumLayout,
  ImageAdapter,
  ImageSource,
  ImageContext,
  TransitionMode,
  LightboxTransitionOption,
  InvalidPhotoPolicy,
  InvalidPhotosEvent,
  PhotoValidationIssue,
  PhotoValidationError,
  LightboxHandle,
  LightboxController,
  LightboxProviderController,
  PhotoLabels,
  PhotoDefaults,
  PhotoCarouselAutoplayOptions,
  ResponsivePhotoSizes,
  ResponsiveParameter,
  LightboxControlsSlotProps,
  LightboxCaptionSlotProps,
  LightboxSlideSlotProps,
  LightboxViewportSlotProps,
  CarouselSlideSlotProps,
  CarouselThumbSlotProps,
  CarouselCaptionSlotProps,
  CarouselControlsSlotProps,
  CarouselDotsSlotProps,
} from '@lupinum/nuxt-photo/app'

PhotoItem<TMeta>

interface PhotoItem<TMeta extends object = Readonly<Record<string, unknown>>> {
  readonly id: string
  readonly src: string
  readonly width: number
  readonly height: number
  readonly thumbSrc?: string
  readonly placeholderSrc?: string
  readonly alt?: string
  readonly caption?: string
  readonly description?: string
  readonly srcset?: string
  readonly meta?: Readonly<TMeta>
}

The data shape every component accepts. id, src, width, height are required.

• PhotoItem concept page

InvalidPhotoPolicy

type InvalidPhotoPolicy = 'throw' | 'drop'

Controls how collection components handle invalid photo data.

• 'throw' - fail loudly. This is the default.
• 'drop' - remove invalid photos and continue rendering valid photos. Use drop only when the app explicitly accepts missing photos for dynamic content. Data behavior is identical in development and production.

InvalidPhotosEvent

type InvalidPhotosEvent = {
  readonly owner: string
  readonly issues: readonly PhotoValidationIssue[]
  readonly rawPhotos: readonly unknown[]
}

Emitted as invalidPhotos when a collection component receives invalid photo data while validation="drop" is set.

Lightbox controllers and handles

PhotoAlbum and PhotoGroup expose the small LightboxHandle through template refs:

interface LightboxHandle {
  open(index?: number): Promise<void>
  openById(id: string): Promise<void>
  close(): Promise<void>
  readonly isOpen: boolean
}

LightboxController is returned by useLightbox() and provideLightbox(). It exposes reactive photos, active photo state, navigation, close, and zoom controls. LightboxProviderController extends it with thumbnail registration for components that own the provider.

PhotoLabels and PhotoDefaults

PhotoLabels contains every visible and assistive label. PhotoDefaults contains shared lightbox defaults that can be provided through PhotoDefaultsKey:

interface PhotoDefaults {
  minZoom?: number
  labels?: Partial<PhotoLabels>
}

Configuration and labels is the canonical reference for label keys and defaults.

PhotoCarouselAutoplayOptions

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

delayMs defaults to 4000. stopOnInteraction defaults to true. stopOnMouseEnter defaults to false. The delay must be greater than zero.

ResponsivePhotoSizes

type ResponsivePhotoSizes = {
  size: string
  sizes?: Array<{ viewport: string; size: string }>
}

Use this layout-aware form for rows albums. PhotoAlbum.sizes also accepts a native HTML sizes string.

Public slot-prop types

The package exports named slot-prop types for custom lightbox and carousel UI:

• LightboxControlsSlotProps
• LightboxCaptionSlotProps
• LightboxSlideSlotProps
• LightboxViewportSlotProps
• CarouselSlideSlotProps
• CarouselThumbSlotProps
• CarouselCaptionSlotProps
• CarouselControlsSlotProps
• CarouselDotsSlotProps

The component reference pages list the fields each slot receives.

PhotoValidationError

A runtime-exported error class with readonly owner and issues fields:

import { PhotoValidationError } from '@lupinum/nuxt-photo/app'

if (error instanceof PhotoValidationError) {
  console.error(error.owner, error.issues)
}

AlbumLayout

Discriminated union of the three layout variants.

type RowsAlbumLayout = {
  type: 'rows'
  targetRowHeight?: ResponsiveParameter<number>
}

type ColumnsAlbumLayout = {
  type: 'columns'
  columns?: ResponsiveParameter<number>
}

type MasonryAlbumLayout = {
  type: 'masonry'
  columns?: ResponsiveParameter<number>
}

type AlbumLayout = RowsAlbumLayout | ColumnsAlbumLayout | MasonryAlbumLayout

TypeScript enforces that targetRowHeight is only valid on rows and columns is only valid on columns/masonry.

ImageAdapter

type ImageAdapter = (photo: PhotoItem, context: ImageContext) => ImageSource

The contract for routing images through a provider. Receives a photo and the render context, returns the <img>-ready source data.

ImageSource

type ImageSource = {
  src: string
  placeholderSrc?: string
  srcset?: string
  sizes?: string
  width?: number
  height?: number
}

The return type of ImageAdapter. Nuxt Photo copies these attributes onto the rendered <img>.

ImageContext

type ImageContext = 'thumb' | 'slide'

Tells an adapter whether the image is being rendered as:

• 'thumb' - a grid thumbnail (smaller target sizes)
• 'slide' - a full lightbox slide (viewport-wide sizes)

TransitionMode

type TransitionMode = 'flip' | 'fade' | 'auto' | 'none'

The FLIP transition strategy - 'auto' (default) picks FLIP when the thumbnail is visible enough, otherwise fades.

• Transitions

LightboxTransitionOption

type LightboxTransitionOption =
  | TransitionMode
  | {
      mode: TransitionMode
      autoThreshold?: number
    }

Either a mode string or an object with a custom autoThreshold (the intersection ratio above which 'auto' uses FLIP). Default autoThreshold is 0.55.

ResponsiveParameter<T>

type ResponsiveParameter<T = number> = T | ((containerWidth: number) => T)

A prop value can be static or responsive to the current container width. Build a responsive value with responsive().

• Responsive parameters