directive developer preview

Directive that improves image loading performance by enforcing best practices.

See more...



Property Description
@Input()rawSrc: string

Name of the source image. Image name will be processed by the image loader and the final URL will be applied as the src property of the image.

@Input()rawSrcset: string

A comma separated list of width or density descriptors. The image name will be taken from rawSrc and combined with the list of width or density descriptors to generate the final srcset property of the image.


<img rawSrc="hello.jpg" rawSrcset="100w, 200w" />  =>
<img src="path/hello.jpg" srcset="path/hello.jpg?w=100 100w, path/hello.jpg?w=200 200w" />
@Input()width: number | undefined

The intrinsic width of the image in pixels.

@Input()height: number | undefined

The intrinsic height of the image in pixels.

@Input()loading?: 'lazy' | 'eager' | 'auto'

The desired loading behavior (lazy, eager, or auto).

Setting images as loading='eager' or loading='auto' marks them as non-priority images. Avoid changing this input for priority images.

@Input()priority: boolean

Indicates whether this image should have a high priority.


NgOptimizedImage ensures that the loading of the Largest Contentful Paint (LCP) image is prioritized by:

  • Automatically setting the fetchpriority attribute on the <img> tag
  • Lazy loading non-priority images by default
  • Asserting that there is a corresponding preconnect link tag in the document head

In addition, the directive:

  • Generates appropriate asset URLs if a corresponding ImageLoader function is provided
  • Requires that width and height are set
  • Warns if width or height have been set incorrectly
  • Warns if the image will be visually distorted when rendered

The NgOptimizedImage directive is marked as standalone and can be imported directly.

Follow the steps below to enable and use the directive:

  1. Import it into the necessary NgModule or a standalone Component.
  2. Optionally provide an ImageLoader if you use an image hosting service.
  3. Update the necessary <img> tags in templates and replace src attributes with rawSrc. Using a rawSrc allows the directive to control when the src gets set, which triggers an image download.

Step 1: import the NgOptimizedImage directive.

import { NgOptimizedImage } from '@angular/common';

// Include it into the necessary NgModule
  imports: [NgOptimizedImage],
class AppModule {}

// ... or a standalone Component
  standalone: true
  imports: [NgOptimizedImage],
class MyStandaloneComponent {}

Step 2: configure a loader.

To use the default loader: no additional code changes are necessary. The URL returned by the generic loader will always match the value of "src". In other words, this loader applies no transformations to the resource URL and the value of the rawSrc attribute will be used as is.

To use an existing loader for a third-party image service: add the provider factory for your chosen service to the providers array. In the example below, the Imgix loader is used:

import {provideImgixLoader} from '@angular/common';

// Call the function and add the result to the `providers` array:
providers: [

The NgOptimizedImage directive provides the following functions:

If you use a different image provider, you can create a custom loader function as described below.

To use a custom loader: provide your loader function as a value for the IMAGE_LOADER DI token.

import {IMAGE_LOADER, ImageLoaderConfig} from '@angular/common';

// Configure the loader using the `IMAGE_LOADER` token.
providers: [
     provide: IMAGE_LOADER,
     useValue: (config: ImageLoaderConfig) => {
       return `https://example.com/${config.src}-${config.width}.jpg}`;

Step 3: update <img> tags in templates to use rawSrc instead of src.

<img rawSrc="logo.png" width="200" height="100">




There are no parameters.

ngOnChanges(changes: SimpleChanges)

changes SimpleChanges



There are no parameters.

© 2010–2022 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.