SSR and layout stability

Server-side rendering (SSR) creates HTML before the browser knows the album's container width. Nuxt Photo uses photo dimensions and an optional width assumption to reduce visible movement during hydration.

Predict hydration stability

Match server assumptions to the same breakpoint the client will use.

Reset

Stable breakpoint Server resolves to 640px; client resolves to 640px.

Code State

Copy

<PhotoAlbum
  :photos="photos"
  :layout="{ type: 'columns', columns: responsive({ 0: 2, 640: 3, 960: 4 }) }"
  :default-container-width="720"
  :breakpoints="[640, 960]"
/>

{
  "serverWidth": 720,
  "clientWidth": 760,
  "serverBreakpoint": 640,
  "clientBreakpoint": 640,
  "stable": true
}

Accurate dimensions come first

Every photo needs intrinsic width and height. These values reserve the correct aspect ratio before the file loads. Missing or approximate dimensions cause visible movement and incorrect layout calculations.

Set a server width for important albums

<PhotoAlbum
  :photos="photos"
  :default-container-width="1280"
  :spacing="responsive({ 0: 4, 640: 8, 1024: 12 })"
/>

The server calculates the album as if its container were 1280 pixels wide. After mount, the component uses the measured container width.

Choose a value close to the album's common rendered width. Above-the-fold columns and masonry layouts benefit most because they need a width to form their final groups.

Snap measurements to known breakpoints

The breakpoints prop limits layout calculation to a known set of widths:

<PhotoAlbum
  :photos="photos"
  :default-container-width="1280"
  :breakpoints="[375, 640, 1024, 1280]"
/>

Responsive values contribute their positive breakpoint keys automatically. Use defaultContainerWidth equal to one of those keys when possible.

No assumption can match every device. The goal is to keep the first render stable for common container widths while preserving correct responsive behavior after measurement.