CLS Prevention

Cumulative Layout Shift (CLS) happens when the browser does not know an image's dimensions before it loads. NgOptimizedImage requires explicit sizing — and ng-image-optimizer preserves that contract through the loader chain.

Required: width and height

Always set width and height (or use fill inside a sized container). The directive uses them to set the intrinsic aspect ratio on the <img> before the optimized asset arrives.

html

<img ngSrc="/product.jpg" width="400" height="400" alt="Product" />

Fill mode

When aspect ratio is unknown, use fill and give the parent explicit dimensions plus position: relative.

html

<div style="width: 100%; height: 240px; position: relative;">
  <img ngSrc="/card.jpg" fill alt="Card" style="object-fit: cover;" />
</div>

How the loaders help

SSR: Sharp resizes to the requested width while preserving aspect ratio; the DOM dimensions you declare stay fixed.
AOT: Each variant matches a width from the breakpoint matrix; Angular still uses your declared width/height for layout, not the file's pixel dimensions.

Placeholder mode

The placeholder attribute loads a tiny variant first. In SSR mode the server caps placeholder quality; in AOT mode the loader requests a small width (≤ 64px) for the placeholder URL.

html

<img
  ngSrc="/hero.jpg"
  width="1200"
  height="630"
  placeholder
  alt="Hero"
/>