Choose a component

Pick Photo, PhotoAlbum, PhotoGroup, or PhotoCarousel for the result you need.

Start with the component that already owns the layout and navigation you need. Most applications use PhotoAlbum.

Responsive albumRows, columns, or masonry with an included lightbox.Shared lightboxOne navigation order across several rendered sections.Swipeable carouselHorizontal browsing with arrows, thumbnails, and autoplay.Custom compositionYour thumbnail layout with Nuxt Photo state and behavior.

Recommended starting point<PhotoAlbum>

Rows, columns, or masonry with an included lightbox.

Open guide

All four components accept the same photo data. Nuxt registers them automatically after you install the module.

`Photo`

Use Photo for one image. Add lightbox when selecting it should open the viewer.

vue

<Photo :photo="cover" lightbox />

Use it for a cover, article image, or any isolated photo. It does not create a multi-photo collection.

Photo reference

`PhotoAlbum`

Use PhotoAlbum for responsive photo rows, columns, or masonry. Its lightbox is enabled by default.

vue

<PhotoAlbum :photos="photos" layout="rows" />

This is the normal starting point for a gallery page.

PhotoAlbum reference

`PhotoGroup`

Use PhotoGroup when several rendered sections must navigate through one explicit photo collection.

vue

<PhotoGroup :photos="allPhotos">
  <PhotoAlbum :photos="landscapes" />
  <PhotoAlbum :photos="portraits" />
</PhotoGroup>

The photos prop defines the shared navigation order. Descendant albums connect their thumbnails by photo ID.

Share one lightbox

`PhotoCarousel`

Use PhotoCarousel for horizontal browsing. Its lightbox is off by default, so enable it only when selecting a slide should open the viewer.

vue

<PhotoCarousel :photos="photos" :lightbox="true" />

The carousel supports arrows, thumbnails, dots, autoplay, looping, and right-to-left direction.

Build a carousel

When ready-made components are not enough

First use component props, CSS variables, and slots. Use LightboxProvider, PhotoTrigger, and the lightbox primitives only when the design requires a different thumbnail layout or lightbox structure.

Customization levels explains the order without requiring you to learn the lower-level API now.