Get started

Install the Nuxt module, paste a complete album page, and check the lightbox. Then replace the sample photos with your own.

In five minutes you have a styled album with a working lightbox.

These docs describe the Nuxt Photo 1.0 beta. Install the next tag.

You need Nuxt 4.4.8 or later in Nuxt 4, and Node 22.18+ or 24.11+.

1. Install the module

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@lupinum/nuxt-photo'],
  nuxtPhoto: {
    css: 'all',
  },
})

The module registers Photo, PhotoAlbum, PhotoGroup, and PhotoCarousel, and auto-imports helpers such as responsive and useLightbox. css: 'all' adds the complete look. Without it you get only the structure CSS, for apps that bring their own theme.

2. Add an album page

app/pages/gallery.vue

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

const photos: PhotoItem[] = [
  {
    id: 'lake',
    src: 'https://picsum.photos/id/1018/1280/800',
    width: 1280,
    height: 800,
    alt: 'Mountain lake under a clear sky',
    caption: 'Lake',
  },
  {
    id: 'forest',
    src: 'https://picsum.photos/id/1015/960/1200',
    width: 960,
    height: 1200,
    alt: 'River running through a valley',
    caption: 'Valley',
  },
  {
    id: 'coast',
    src: 'https://picsum.photos/id/1020/1200/800',
    width: 1200,
    height: 800,
    alt: 'Bear walking along a stony shore',
    caption: 'Shore',
  },
]
</script>

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

The sample URLs contain their sizes, so the page works before you add files.

3. Check the result

Start the dev server and open /gallery:

The three photos fill the width in justified rows, with no jump while they load.
Selecting a photo opens the lightbox from the thumbnail.
ArrowLeft and ArrowRight change the photo; a click zooms to real pixels.
Escape closes the lightbox and focus returns to the thumbnail.

4. Use your own photos

Replace the array with your data. Each photo needs:

Field	Rule
`id`	Stable and unique in the collection. Not the array index.
`src`	Image URL or public path.
`width`	Real pixel width of the image file, not its displayed size.
`height`	Real pixel height of the image file.

Add alt for every image that is not decorative. caption and description appear in the lightbox.

Wrong width or height values still render, but the layout and the opening animation are wrong. Read the sizes from the file, your CMS, or your upload pipeline.

Data from a CMS or an API: Use your own photos. Resized and modern image formats: Deliver images.

Questions? Ask in the Lupinum OSS Discord.