NgOptimizedImage is a standalone Angular directive for improving image loading in large applications. Applied through ngSrc rather than src, it helps control loading behavior, image priority, dimensions, responsive variants, and CDN URL generation. Its purpose is to improve meaningful visual rendering, especially Largest Contentful Paint (LCP), while avoiding distorted images caused by mismatched dimensions. section 4.4 section 4.7
Import the directive into a component and bind an image URL with ngSrc. Supply width and height so the rendered image has known dimensions. By default, generated images use lazy loading and fetchpriority="auto": they load when brought into the viewport, while the browser determines their relative priority. section 4.4.1
Listing 4.13 Using the NgOptimizedDirective
<tr *ngFor="let employee of employees$ | async">
<td>
<img
[ngSrc]="employee.profilePicture" #1
width="20" height="20"/> #2
<a [routerLink]="['/employees/details', employee.id]">
{{ employee.firstName }} {{ employee.lastName }}
</a>
</td>
</tr>
A table row binds each employee profile URL to ngSrc and declares 20-by-20 dimensions, combining optimized loading with a realistic routed employee list. section 4.4.1
Use priority for the main image that defines a page, such as an employee profile picture on a details view. It produces high fetch priority to improve LCP. Do not prioritize multiple images on the same page: competing priority images can reduce performance. Use loading="eager" only when an image must load immediately despite being outside the viewport. section 4.4.2
NgOptimizedImage also supports responsive delivery and CDN-based transformation:
- Set sizes to have the directive generate a srcset, letting the browser select an image version appropriate to the viewport. section 4.4.3
- Add a preconnect link for a custom CDN origin so the LCP image can begin loading over an early connection. section 4.4.3
- Configure a built-in CDN loader or provide IMAGE_LOADER for a CDN with its own URL contract. section 4.4.3
Profile image versus project images
On an employee details page, mark the central profile picture as priority. Leave project-card images unprioritized so they do not compete with the page’s LCP image; set eager loading only when those images truly need immediate loading. section 4.4.2
