Image

NG-ZORRO experiments are features that are released but not yet considered stable or production ready

Developers and users can opt-in into these features before they are fully released. But breaking changes may occur with any release.

When To Use#

  • When you need the browser to prioritize image loading (needs to be handled in SSR).
  • When you need to optimize for HD displays (e.g. retina screens).
  • When using image CDN.
  • More in Image documentation
  • Next steps
    • Add sizes attribute and responsive support.
import { NzImageModule } from 'ng-zorro-antd/experimental/image';

Examples

Priority

Setting nzPriority will add the <link rel="preload"> tag when rendering server-side (SSR), and browsers will treat it as a high priority resource to load. You can see this in MDN - Preloading, web.dev - Preloading responsive images to learn more.

Note: usually we only need to set nzPriority for the first screen images, so you only need to add it for the first few items in the cyclically generated template, e.g.

@for (product of products; track product)
  <nz-image [nzPriority]="$index <= 8"></nz-image>
}
expand codeexpand code
      Loading...
Use Src Loader

Custom nzSrcLoader is used to resolve image URLs, or you can also use the built-in image CND provider's Loaders.
We recommend always specifying the image size (nzWidth, nzHeight), which can help improve the key metrics of the web experience CLS, and can also be used with the Loader to optimize the images using the image CND to improve the loading speed.
If you want to use a different Loader in a different environment you can do the following.

import { environment } from 'environments/environment';

import { NzConfig, provideNzConfig } from 'ng-zorro-antd/core/config';
import { createAliObjectsLoader, defaultImageSrcLoader } from 'ng-zorro-antd/experimental/image';

const nzConfig: NzConfig = {
  imageExperimental: {
    nzSrcLoader: environment.production ? createAliObjectsLoader('https://zos.alipayobjects.com/rmsportal') : defaultImageSrcLoader
  }
};

@NgModule({
  // ...
  providers: [
    provideNzConfig(nzConfig)
  ]
})
export class AppModule {}
expand codeexpand code
      Loading...
Auto Srcset

Using nzAutoSrcset requires to specify the image size (nzWidth, nzHeight), with the Loader automatically generating srcset for different pixel densities.

expand codeexpand code
      Loading...

API#

nz-image#

PropertyDescriptionTypeDefaultGlobal Config
nzSrcURLstring-
nzAltAltstring-
nzWidthWidthnumber|stringauto
nzHeightHeightnumber|stringauto
nzAutoSrcsetWhether to optimize image loadingbooleanfalse✅
nzSrcLoaderLoaderNzImageSrcLoaderdefaultImageSrcLoader✅
nzPriorityWhether to add preload (only SSR)booleanfalse✅

NzImageSrcLoader#

export type NzImageSrcLoader = (params: { src: string; width: number }) => string;

Note#

nzSrcLoader#

Using nzSrcLoader helps you to fill in key information about the requested image, such as src and width, which defaults to

export const defaultImageSrcLoader: NzImageSrcLoader = ({ src }) => {
  return src;
};

Built-in image CND creation method


/**
 * AliObjectsLoader return format
 * {domain}/{src}?x-oss-process=image/resize,w_{width}
 */
export function createAliObjectsLoader(domain: string): NzImageSrcLoader;

/**
 * ImgixLoader return format
 * {domain}/{src}?format=auto&fit=max&w={width}
 */
export function createImgixLoader(domain: string): NzImageSrcLoader;

/**
 * CloudinaryLoader return format
 * {domain}/c_limit,q_auto,w_{width}/{src}
 */
export function createCloudinaryLoader(domain: string): NzImageSrcLoader;

Responsive images and preloaded images#

Using responsive images can help web pages display well on different devices. Preloading images can help you load images faster, for more information please refer to.