Note: the NgOptimizedImage
directive is currently in the “Developer Preview” mode. The Angular team will stabilize the APIs based on the feedback and will make an announcement once the APIs are fully stable.
The NgOptimizedImage
directive makes it easy to adopt performance best practices for loading images.
The NgOptimizedImage
directive ensures that the loading of the Largest Contentful Paint image is prioritized by:
fetchpriority
attribute on the <img>
tagIn addition to optimizing the loading of the LCP image, NgOptimizedImage
enforces a number of image best practices:
width
and height
are setwidth
or height
have been set incorrectlyYou will need to import the directive into your application. In addition, you will need to setup an image loader. These steps are explained in the Setting up NgOptimizedImage
tutorial.
To activate the NgOptimizedImage
directive, replace your image's src
attribute with rawSrc
.
<img rawSrc=”cat.jpg" width="400" height="200">
The built-in third-party loaders prepend a shared base URL to src
. If you're using one of these loaders (or any other loader that does this), make sure to omit the shared base URL path from src
to prevent unnecessary duplication.
You must also set the width
and height
attributes. This is done to prevent image-related layout shifts. The width
and height
attributes should reflect the intrinsic size of the image. During development, the NgOptimizedImage
warns if it detects that the width
and height
attributes have been set incorrectly.
priority
Always mark the LCP image on your page as priority
to prioritize its loading.
<img rawSrc="cat.jpg" width="400" height="200" priority>
Marking an image as priority
applies the following optimizations:
fetchpriority=high
(read more about priority hints here)loading=eager
(read more about native lazy loading here)Angular displays a warning during development if the LCP element is an image that does not have the priority
attribute. A page’s LCP element can vary based on a number of factors - such as the dimensions of a user's screen. A page may have multiple images that should be marked priority
. See CSS for Web Vitals for more details.
You can add a preconnect
resource hint for your image origin to ensure that the LCP image loads as quickly as possible. Always put resource hints in the <head>
of the document.
<link rel="preconnect" href="https://my.cdn.origin" >
By default, if you use a loader for a third-party image service, the NgOptimizedImage
directive will warn during development if it detects that there is no preconnect
resource hint for the origin that serves the LCP image.
To disable these warnings, add {ensurePreconnect: false}
to the arguments passed to the provider factory for your chosen image service:
providers: [ provideImgixLoader('https://my.base.url', {ensurePreconnect: false}) ],
Depending on the image's styling, adding width
and height
attributes may cause the image to render differently. NgOptimizedImage
warns you if your image styling renders the image at a distorted aspect ratio.
You can typically fix this by adding height: auto
or width: auto
to your image styles. For more information, see the web.dev article on the <img>
tag.
srcset
attributesIf your <img>
tag defines a srcset
attribute, replace it with rawSrcset
.
<img rawSrc="hero.jpg" rawSrcset="100w, 200w, 300w">
If the rawSrcset
attribute is present, NgOptimizedImage
generates and sets the srcset
attribute using the configured image loader. Do not include image file names in rawSrcset
- the directive infers this information from rawSrc
. The directive supports both width descriptors (e.g. 100w
) and density descriptors (e.g. 1x
) are supported.
You can also use rawSrcset
with the standard image sizes
attribute.
<img rawSrc="hero.jpg" rawSrcset="100w, 200w, 300w" sizes=”50vw”>
By default, NgOptimizedImage
sets loading=lazy
for all images that are not marked priority
. You can disable this behavior for non-priority images by setting the loading
attribute. This attribute accepts values: eager
, auto
, and lazy
. See the documentation for the standard image loading
attribute for details.
<img rawSrc="cat.jpg" width="400" height="200" loading="eager">
© 2010–2022 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://angular.io/guide/image-directive