NgOptimizedImage
Directive that improves image loading performance by enforcing best practices.
Selectors
Properties
Property | Description |
---|---|
@Input('{ required: true, transform: unwrapSafeUrl }')
|
Name of the source image.
Image name will be processed by the image loader and the final URL will be applied as the |
@Input()
|
A comma separated list of width or density descriptors.
The image name will be taken from Example:
|
@Input()
|
The base |
@Input('{ transform: numberAttribute }')
|
For responsive images: the intrinsic width of the image in pixels. For fixed size images: the desired rendered width of the image in pixels. |
@Input('{ transform: numberAttribute }')
|
For responsive images: the intrinsic height of the image in pixels. For fixed size images: the desired rendered height of the image in pixels. |
@Input()
|
The desired loading behavior (lazy, eager, or auto). Defaults to Warning: Setting images as loading="eager" or loading="auto" marks them
as non-priority images and can hurt loading performance. For images which
may be the LCP element, use the |
@Input('{ transform: booleanAttribute }')
|
Indicates whether this image should have a high priority. |
@Input()
|
Data to pass through to custom loaders. |
@Input('{ transform: booleanAttribute }')
|
Disables automatic srcset generation for this image. |
@Input('{ transform: booleanAttribute }')
|
Sets the image to "fill mode", which eliminates the height/width requirement and adds styles such that the image fills its containing element. |
@Input('{ transform: booleanOrDataUrlAttribute }')
|
A URL or data URL for an image to be used as a placeholder while this image loads. |
@Input()
|
Configuration object for placeholder settings. Options:
|
Description
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
- Automatically generating a preconnect link tag in the document head
In addition, the directive:
- Generates appropriate asset URLs if a corresponding
ImageLoader
function is provided - Automatically generates a srcset
- Requires that
width
andheight
are set - Warns if
width
orheight
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:
- Import it into the necessary NgModule or a standalone Component.
- Optionally provide an
ImageLoader
if you use an image hosting service. - Update the necessary
<img>
tags in templates and replacesrc
attributes withngSrc
. Using angSrc
allows the directive to control when thesrc
gets set, which triggers an image download.
Step 1: import the NgOptimizedImage
directive.
import { NgOptimizedImage } from '@angular/common';
// Include it into the necessary NgModule
@NgModule({
imports: [NgOptimizedImage],
})
class AppModule {}
// ... or a standalone Component
@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 ngSrc
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: [
provideImgixLoader("https://my.base.url/"),
],
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 ngSrc
instead of src
.
<img ngSrc="logo.png" width="200" height="100">