Northern coastline of Mallorca, Spain — Photo by author
Since the release of the NgOptimizedImage directive two major versions ago in Angular 14.2 (recently backported to version 13.4), front-end developers have been able to reuse Angular logic to render images in the browser performantly.
This built-in directive addresses some frequently overlooked best practices in image rendering, such as declaring fetch priority, adding hints for eager or lazy loading, and providing multiple image sources for the browser to select based on the user’s screen size. Whether or not a web interface is heavy on images, the proper usage of NgOptimizedImage helps it load faster, enhancing the user experience.
Inalterable values of optimized image properties
A limitation with the updatability of the input properties of this directive discouraged a few developers from using it. Particularly relevant, the ngSrc property — which instructs the compiler to run the image optimizations — was not supposed to have its value changed after the directive’s initialization.
Anyone who attempted to do this, as in the scenario of allowing users to change an image bound to the NgOptimizedImage directive, encountered this error log on a browser console:
Runtime error when altering the ngSrc property value of a NgOptimizedImage element in Angular < 16.2
If we compile and render the standalone component of the following code example in an Angular version between 13.4.x and 16.1.x, we will certainly trigger the NG02953 UNEXPECTED_INPUT_CHANGE runtime error.
https://medium.com/media/62c554c38e779bd3d024cc17f37f9030/href
Updatable image sources from Angular 16.2
With the release of Angular 16.2.0, it is now possible to change the ngSrc property value after the NgOptimizedImage directive has been initialized.
There’s no need to approach lengthy workarounds anymore, like wrapping the optimized image element in an <ng-template> for embedded views to enable these value updates at runtime — unless you want to change other image properties at the risk of impacting visual stability on the browser viewport.
So far, ngSrc is the only property allowed to be modified. Alex Castle, the code contributor to this directive enhancement, advised in the corresponding pull request that “modifying certain inputs, such as height, width and fill would be very likely to cause layout shift, which NgOptimizedImage is specifically designed to prevent.”
Even when replacing the source with a different image under the same aspect ratio, be mindful of its visual relevance in the user interface. Switching images recognized as LCP elements at runtime could slow the web loading performance. Thankfully, Angular throws the warning log NG02964 LCP_IMG_NGSRC_MODIFIED to alert us proactively.
So please use the new modifiable capabilities with caution and always make sure to run performance audits using both synthetic tools — like Lighthouse — and real user monitoring services to keep measuring if web images remain properly optimized.
La versión en español de este artículo también se encuentra disponible en el blog de ng-conf:
Modificando la fuente de imágenes optimizadas con Angular 16.2
Modifiable Source of Optimized Images in Angular 16.2 was originally published in ngconf on Medium, where people are continuing the conversation by highlighting and responding to this story.