Image delivery
Understand native images, Nuxt Image, custom adapters, loading, and placeholders.
Every built-in image passes through an image adapter. The adapter returns the
final src, srcset, sizes, dimensions, and optional placeholder for a
thumbnail or lightbox slide.
Inspect the image pipeline
See the final attributes produced for thumbnail and lightbox contexts.
<PhotoImage :photo="photo" context="thumb" :image-adapter="nativeAdapter" />Choose one delivery path
| Path | Use it when |
|---|---|
auto | You want Nuxt Image when installed and native images otherwise. |
native | Your files or CDN URLs are already prepared for the browser. |
nuxt-image | You want Nuxt Image transformations and responsive candidates. |
| Custom | Your image service needs application-specific URL generation. |
auto is the default. Its native fallback is expected and does not warn.
The native adapter uses thumbSrc for thumbnails when present and src for
slides. It passes through srcset and native sizes values. The Nuxt Image
adapter generates responsive URLs from its configured provider.
Use the Nuxt Image guide or the custom image service guide for setup.
Loading behavior
PhotoImage uses native lazy loading by default. Ready-made components can use
eager loading for images that must appear immediately. The browser still owns
request scheduling and candidate selection.
Use a sizes value that describes the rendered image width. This helps the
browser select an appropriate srcset candidate instead of downloading a file
larger than the layout needs.
Placeholders
placeholderSrc is rendered as a background until the main image loads. It
resets when the adapter produces a different src, srcset, or sizes request.
If the main image fails, the placeholder remains visible.
This behavior applies to native, Nuxt Image, and custom adapters because the
adapter returns the same ImageSource shape.
Server rendering
An adapter must return the same result for the same photo and context on the server and client. Do not sign URLs from the current time or random state during render. Prepare stable URLs before rendering or use a deterministic service URL.