# Nuxt Photo

> Photo galleries, lightboxes, and carousels for Nuxt with predictable SSR layouts and real image data.

## When to use

Use this site to build photo galleries, lightboxes, and carousels with Nuxt Photo.

## Documentation

- [Introduction](https://nuxt-photo.lupinum.com/raw/docs/start/introduction.md): Photo albums, a lightbox, and a carousel for Nuxt. Server-rendered layout from known image sizes, one photo shape for every component, and which component to use.
- [Get started](https://nuxt-photo.lupinum.com/raw/docs/start/get-started.md): Install the Nuxt module, paste a complete album page, and check the lightbox. Then replace the sample photos with your own.
- [Examples](https://nuxt-photo.lupinum.com/raw/docs/start/examples.md): Complete, copyable components that run on the page - portfolio grid with captions and crossfade, photos in an article, product carousel, Tailwind lightbox, custom caption and counter, and a custom viewer.
- [AI coding agents](https://nuxt-photo.lupinum.com/raw/docs/start/ai-agents.md): Give Claude Code, Codex, Cursor, and other agents the Nuxt Photo docs for the installed version through one AGENTS.md pointer, plus llms.txt, Markdown pages, and the docs MCP server.
- [Use Nuxt Photo with Vue](https://nuxt-photo.lupinum.com/raw/docs/start/plain-vue.md): Use the components in a plain Vue 3 app with Vite - install @lupinum/vue-photo, import components and the stylesheet, set labels, lightbox and image provider once with createPhoto, and deliver images without Nuxt Image.
- [Compare gallery approaches](https://nuxt-photo.lupinum.com/raw/docs/start/compare-approaches.md): Nuxt Photo compared with PhotoSwipe, lightGallery, Nuxt Image, and a custom stack - album layout, lightbox, carousel, image delivery, video, and licensing.
- [Performance and bundle size](https://nuxt-photo.lupinum.com/raw/docs/start/performance-and-bundle-size.md): Measured client bundle size for the Nuxt module, PhotoAlbum, and single Vue imports, and how to keep image cost low.
- [Use your own photos](https://nuxt-photo.lupinum.com/raw/docs/guides/use-your-photos.md): Show a folder from public/ with usePhotoFolder, map CMS or API records to PhotoItem, get real image width and height at upload or from localImages, keep IDs stable, type custom meta data, and handle invalid records with validation="drop".
- [Responsive layouts and SSR](https://nuxt-photo.lupinum.com/raw/docs/guides/responsive-layouts.md): Choose rows, columns, masonry, grid, bento, mosaic, or accordion, set row height, columns, and spacing per container width with responsive(), crop photos into tiles with a featured photo or a +N count, and prevent layout shift during SSR and hydration with defaultContainerWidth and breakpoints.
- [Share one lightbox](https://nuxt-photo.lupinum.com/raw/docs/guides/share-one-lightbox.md): Let several albums and single photos on one page share one lightbox and one next/previous order with PhotoGroup. Collection rules, missing IDs, and turning the lightbox off.
- [Build a carousel](https://nuxt-photo.lupinum.com/raw/docs/guides/build-a-carousel.md): Horizontal photo browsing with PhotoCarousel - thumbnails, arrows, dots, loop, autoplay, several visible slides, right-to-left pages, custom controls, and an optional lightbox.
- [Deliver images](https://nuxt-photo.lupinum.com/raw/docs/guides/deliver-images.md): How Nuxt Photo sizes every thumbnail, slide and photo - srcset from your Nuxt Image screens, sizes from the layout, priority and preload for the first screen, build-time blur placeholders, browser cache headers, and the Nuxt Image config for Vercel, static sites, IPX and Cloudinary.
- [Integrate a custom image service](https://nuxt-photo.lupinum.com/raw/docs/guides/integrate-a-custom-image-service.md): Connect your own CDN, CMS image API, signed URLs or hand-built Cloudinary URLs with a PhotoProvider - a url function per width, optional placeholders, fixed renditions with srcset, a Nuxt Image custom provider for the whole app, per-component providers, and unit tests.
- [Style and theme](https://nuxt-photo.lupinum.com/raw/docs/guides/style-and-theme.md): Change the look of albums and the lightbox - css all vs structure, CSS variables for colors, buttons, mat, glow and placeholders, ui classes, scoped styles, dark themes, and Tailwind CSS with a complete Tailwind lightbox.
- [Customize the lightbox](https://nuxt-photo.lupinum.com/raw/docs/guides/customize-the-built-in-lightbox.md): Change the built-in lightbox without rebuilding it - download, share and full screen buttons, custom caption, counter, tool and action buttons with slots, slide overlays, fade or crossfade navigation, one lightbox for the whole app, and when to use lower-level components instead.
- [Create a custom thumbnail layout](https://nuxt-photo.lupinum.com/raw/docs/guides/create-a-custom-thumbnail-layout.md): Render thumbnails in any layout you build yourself - a grid, a hexagon grid, a list - and keep the built-in lightbox, keyboard access, and opening animation with LightboxProvider, PhotoTrigger, and PhotoImage.
- [Build a lightbox from primitives](https://nuxt-photo.lupinum.com/raw/docs/guides/build-a-lightbox-from-primitives.md): Write your own lightbox markup and CSS with LightboxRoot, LightboxViewport, LightboxSlide, LightboxControls, and LightboxCaption, while Nuxt Photo keeps state, gestures, zoom, focus, and the opening animation. Frame variables and an accessibility checklist.
- [Control the lightbox from code](https://nuxt-photo.lupinum.com/raw/docs/guides/control-the-lightbox.md): Open the lightbox at a given photo from a button, bind the active photo with v-model:active, close it with the browser Back button, link to a photo with deepLink, and move next and previous with template refs or useLightbox().
- [Reference](https://nuxt-photo.lupinum.com/raw/docs/reference.md): Where to look up exact names, props, defaults, events, slots, composables, types, module options, CSS variables, and package exports.
- [Photo](https://nuxt-photo.lupinum.com/raw/docs/reference/photo.md): The Photo component - props, slots, and behavior for one photo with an optional one-photo lightbox, alone or inside a PhotoGroup.
- [PhotoAlbum](https://nuxt-photo.lupinum.com/raw/docs/reference/photo-album.md): The PhotoAlbum component - props, layout options, events, the thumbnail slot, and the template ref for rows, columns, masonry, grid, bento, mosaic, and accordion albums.
- [PhotoGroup](https://nuxt-photo.lupinum.com/raw/docs/reference/photo-group.md): The PhotoGroup component - props, events, slot, and template ref for one lightbox and navigation order across several albums and photos.
- [PhotoCarousel](https://nuxt-photo.lupinum.com/raw/docs/reference/photo-carousel.md): The PhotoCarousel component - every prop, event, and slot for thumbnails, arrows, dots, loop, autoplay, controls, and the optional lightbox.
- [Lightbox](https://nuxt-photo.lupinum.com/raw/docs/reference/lightbox.md): The built-in Lightbox component - slots, keyboard shortcuts, mouse and touch gestures, zoom, opening animation, slide/fade/crossfade navigation, reduced motion, and focus behavior.
- [Primitives](https://nuxt-photo.lupinum.com/raw/docs/reference/primitives.md): Lower-level lightbox components for your own markup - LightboxProvider, LightboxRoot, LightboxOverlay, LightboxAmbient, LightboxViewport, LightboxSlide, LightboxControls, LightboxCaption, PhotoTrigger, PhotoImage.
- [Composables](https://nuxt-photo.lupinum.com/raw/docs/reference/composables.md): Public helpers for lightbox state, reactive labels, async local folders, photo validation, providers, and responsive values.
- [Configuration and labels](https://nuxt-photo.lupinum.com/raw/docs/reference/configuration-and-labels.md): PhotoConfig, Nuxt module options, providers, lightbox defaults, precedence, ten locales, and label templates.
- [Types](https://nuxt-photo.lupinum.com/raw/docs/reference/types.md): The complete public types for photos, providers, configuration, gallery handles, controllers, layouts, validation, labels, UI classes, and slots.
- [CSS](https://nuxt-photo.lupinum.com/raw/docs/reference/css.md): Every CSS class and CSS variable - lightbox mat, colors, buttons, glow, carousel, album - and the none, structure, and all CSS modes.
- [Package exports](https://nuxt-photo.lupinum.com/raw/docs/reference/package-exports.md): The supported import paths for Nuxt (@lupinum/nuxt-photo/app) and plain Vue (@lupinum/vue-photo), and everything each one exports.
- [Troubleshooting](https://nuxt-photo.lupinum.com/raw/docs/help/troubleshooting.md): Fix Nuxt Photo problems by error message or by what you see - invalid photo data, missing IDs in a PhotoGroup, missing lightbox context, Nuxt Image errors, hydration mismatches, unstyled albums, layout jumps, and lightbox clicks.
- [Known constraints](https://nuxt-photo.lupinum.com/raw/docs/help/known-constraints.md): What Nuxt Photo 1.0 does not do and which options are read only at mount - known image sizes, photos only, setup-time lightbox, one open lightbox, required structure CSS, limited carousel options, Vercel image limits, and sizes=auto support.