more_horiz
@angular/commoncode
NgOptimizedImage
directive
stable
Directive that improves image loading performance by enforcing best practices.
Image Optimization GuideOn this page
API
class NgOptimizedImage implements OnInit ,OnChanges { @Input() ngSrc: string; @Input() ngSrcset: string; @Input() sizes?: string | undefined; @Input() width: number | undefined; @Input() height: number | undefined; @Input() decoding?: "auto" | "sync" | "async" | undefined; @Input() loading?: "auto" | "lazy" | "eager" | undefined; @Input() priority: boolean; @Input() loaderParams?: { [key: string]: any; } | undefined; @Input() disableOptimizedSrcset: boolean; @Input() fill: boolean; @Input() placeholder?: string | boolean | undefined; @Input() placeholderConfig?: ImagePlaceholderConfig | undefined; protected generatePlaceholder(placeholderInput: string | boolean): string | boolean | null; protected shouldBlurPlaceholder(placeholderConfig?: ImagePlaceholderConfig | undefined): boolean;}
ngSrc
stringName 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.
ngSrcset
stringA comma separated list of width or density descriptors.
The image name will be taken from ngSrc and combined with the list of width or density
descriptors to generate the final srcset property of the image.
Example:
<img ngSrc="hello.jpg" ngSrcset="100w, 200w" /> =>
<img src="path/hello.jpg" srcset="path/hello.jpg?w=100 100w, path/hello.jpg?w=200 200w" />sizes
string | undefinedThe base sizes attribute passed through to the <img> element.
Providing sizes causes the image to create an automatic responsive srcset.
width
number | undefinedFor responsive images: the intrinsic width of the image in pixels. For fixed size images: the desired rendered width of the image in pixels.
height
number | undefinedFor responsive images: the intrinsic height of the image in pixels. For fixed size images: the desired rendered height of the image in pixels.
decoding
"auto" | "sync" | "async" | undefinedThe desired decoding behavior for the image. Defaults to auto
if not explicitly set, matching native browser behavior.
Use async to decode the image off the main thread (non-blocking),
sync for immediate decoding (blocking), or auto to let the
browser decide the optimal strategy.
loading
"auto" | "lazy" | "eager" | undefinedThe desired loading behavior (lazy, eager, or auto). Defaults to lazy,
which is recommended for most images.
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 priority attribute instead of loading.
fill
booleanSets the image to "fill mode", which eliminates the height/width requirement and adds styles such that the image fills its containing element.
placeholder
string | boolean | undefinedA URL or data URL for an image to be used as a placeholder while this image loads.
placeholderConfig
ImagePlaceholderConfig | undefinedConfiguration object for placeholder settings. Options:
- blur: Setting this to false disables the automatic CSS blur.
generatePlaceholder
string | boolean | nullReturns an image url formatted for use with the CSS background-image property. Expects one of:
- A base64 encoded image, which is wrapped and passed through.
- A boolean. If true, calls the image loader to generate a small placeholder url.
@paramplaceholderInput
string | boolean@returns
string | boolean | nullshouldBlurPlaceholder
booleanDetermines if blur should be applied, based on an optional boolean
property blur within the optional configuration object placeholderConfig.
@returns
booleanDescription
Directive that improves image loading performance by enforcing best practices.
NgOptimizedImage ensures that the loading of the Largest Contentful Paint (LCP) image is
prioritized by:
- Automatically setting the
fetchpriorityattribute 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
ImageLoaderfunction is provided - Automatically generates a srcset
- Requires that
widthandheightare set - Warns if
widthorheighthave been set incorrectly - Warns if the image will be visually distorted when rendered
Usage Notes
Follow the steps below to enable and use the directive:
- Import it into a Component.
- Optionally provide an
ImageLoaderif you use an image hosting service. - Update the necessary
<img>tags in templates and replacesrcattributes withngSrc. Using angSrcallows the directive to control when thesrcgets set, which triggers an image download.
Step 1: import the NgOptimizedImage directive.
@Component({
imports: [NgOptimizedImage],
})
class MyPage {}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">Jump to details