Configuration and labels

Every module option, with defaults and when to change them.

Configure Nuxt Photo under the nuxtPhoto key in nuxt.config. Every option is optional - the defaults work for a typical Nuxt app.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@lupinum/nuxt-photo'],
  nuxtPhoto: {
    autoImports: true,
    components: { prefix: '', primitives: false },
    css: 'structure',
    image: { provider: 'auto' },
    labels: { close: 'Close viewer' },
  },
})

`autoImports`

Type: boolean | { prefix?: string }
Default: true

Controls whether Nuxt Photo helpers (useLightbox, provideLightbox, usePhotoLabels, responsive) are auto-imported.

nuxtPhoto: {
  autoImports: false // manually import from '@lupinum/nuxt-photo/app'
}

Turn this off only if you want tight control over your imports or you are importing the composables manually. Nuxt apps should use the supported @lupinum/nuxt-photo/app facade. If app code deliberately imports from @lupinum/vue-photo directly, list @lupinum/vue-photo in your app dependencies.

nuxtPhoto: {
  autoImports: {
    prefix: 'Np'
  }
  // useNpLightbox, npProvideLightbox, npResponsive
}

Use a prefix only when you need it to avoid collisions.

`components`

Type: boolean | { prefix?: string; primitives?: boolean }
Default: { prefix: '', primitives: false }

Registers ready-made components (<Photo>, <PhotoAlbum>, <PhotoGroup>, <PhotoCarousel>) with an optional prefix. Lightbox primitives stay import-only unless primitives: true is set.

// Disable auto-registration
nuxtPhoto: {
  components: false
}

// Add a prefix to avoid collisions
nuxtPhoto: {
  components: {
    prefix: 'Np'
  }
  // <NpPhoto>, <NpPhotoAlbum>, <NpPhotoCarousel>, …
}

// Also auto-register advanced primitives
nuxtPhoto: {
  components: {
    primitives: true
  }
  // <LightboxProvider>, <LightboxRoot>, <PhotoTrigger>, …
}

Use a prefix when another module exposes components with the same names. Enable primitive registration only when you are composing a custom lightbox from Nuxt templates instead of direct imports.

`css`

Type: 'none' | 'structure' | 'all'
Default: 'structure'

Controls which stylesheets are loaded.

Value	Loaded content	When to use
`'none'`	Nothing	You have a custom design system and style every class yourself.
`'structure'`	Layout + geometry CSS only	You want structural correctness but want to theme colors, transitions, and spacing yourself.
`'all'`	Structure + default theme	You want the library to look good out of the box.

nuxtPhoto: {
  css: 'all' // default theme colors and transitions
}

'structure' is the minimum viable setting. Disabling it entirely breaks layouts because the grid math depends on the structure CSS.

CSS reference and custom theming

`image`

Type: false | { provider?: 'auto' | 'nuxt-image' | 'native'; thumb?: object; slide?: object }
Default: { provider: 'auto' }

Picks the image pipeline. The built-in Nuxt Image adapter has defaults for thumbnails and slides; configure them here when the defaults do not match your layout.

Value	Behavior
`'auto'`	Uses `@nuxt/image` when installed. Otherwise, it falls back to `native`.
`'nuxt-image'`	Routes every image through `@nuxt/image`. Reports an error when it is not installed.
`'native'`	Uses browser `<img>` with your `src` and optional `srcset` unchanged.
`false`	Disables module adapter registration. Provide `ImageAdapterKey` yourself for custom pipelines.

Nuxt applications import ImageAdapterKey from @lupinum/nuxt-photo/app.

// Force @nuxt/image instead of using auto fallback
nuxtPhoto: {
  image: {
    provider: 'nuxt-image',
    thumb: {
      sizes: 'sm:100vw md:50vw lg:400px',
      quality: 80,
    },
    slide: {
      widths: [640, 960, 1240, 1600, 2000],
      maxWidth: 1240,
      maxDensity: 1.5,
      sizes: 'min(1240px, calc(100vw - 72px))',
      quality: 85,
    },
  }
}

// Keep images out of any optimization pipeline
nuxtPhoto: {
  image: {
    provider: 'native'
  }
}

// Disable the adapter entirely
nuxtPhoto: {
  image: false
}

How image providers work

Type: { minZoom?: number }
Default: no module-level override

Sets app-wide lightbox defaults when you opt in.

nuxtPhoto: {
  lightbox: {
    minZoom: 1.2 // allow zooming slightly past the fit-to-frame size
  }
}

If you omit lightbox, Nuxt Photo leaves the global default alone and the viewer falls back to its built-in zoom behavior. Per-lightbox overrides are still possible through provideLightbox(photos, { minZoom }) when you build a custom lightbox.

`labels`

Type: a partial object of built-in label strings
Default: frozen English labels

Localizes every visible string and assistive label. Static labels accept plain strings. Indexed labels use {index}; slideStatus also supports {count}.

Label	Default	Used for
`photoViewer`	`Photo viewer`	Lightbox accessible name
`previous`	`Previous`	Previous photo control
`next`	`Next`	Next photo control
`zoom`	`Zoom`	Zoom control
`fit`	`Fit`	Reset zoom control
`close`	`Close`	Close control
`loadFailed`	`Image could not be loaded.`	Image failure message
`previousSlide`	`Previous slide`	Carousel previous control
`nextSlide`	`Next slide`	Carousel next control
`goToSlide`	`Go to slide {index}`	Carousel dot and thumbnail label
`viewPhoto`	`View photo {index}`	Photo trigger label
`slideStatus`	`Slide {index} of {count}`	Polite slide announcement

nuxt.config.ts

export default defineNuxtConfig({
  nuxtPhoto: {
    labels: {
      photoViewer: 'Fotobetrachter',
      previous: 'Vorheriges Foto',
      next: 'Nächstes Foto',
      zoom: 'Vergrößern',
      fit: 'Einpassen',
      close: 'Schließen',
      loadFailed: 'Das Bild konnte nicht geladen werden.',
      previousSlide: 'Vorheriges Bild',
      nextSlide: 'Nächstes Bild',
      goToSlide: 'Gehe zu Bild {index}',
      viewPhoto: 'Foto {index} ansehen',
      slideStatus: 'Bild {index} von {count}',
    },
  },
})

You can set the same typed values under app.config.ts at runtime. Module options override only the label keys they manage; other app-config values remain unchanged.

app.config.ts

export default defineAppConfig({
  nuxtPhoto: {
    labels: {
      close: 'Schließen',
    },
  },
})

Full example

A production-ish config with @nuxt/image, full theming, and a component prefix:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxt/image', '@lupinum/nuxt-photo'],
  image: {
    // your @nuxt/image provider config
    provider: 'cloudinary',
    cloudinary: {
      baseURL: 'https://res.cloudinary.com/your-cloud/image/upload/',
    },
  },
  nuxtPhoto: {
    css: 'all',
    image: { provider: 'nuxt-image' },
    components: { prefix: 'Np' },
    lightbox: { minZoom: 1.2 },
    labels: { close: 'Close photo viewer' },
  },
})

Review the photo model

Use the PhotoItem model to supply the required identifiers, dimensions, and sources.