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.

<ng-container *ngFor="let product of products; index as i">
  <nz-image ... [nzPriority]="i <= 8"></nz-image>
</ng-container>

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, NZ_CONFIG } from 'ng-zorro-antd/core/config';
import { createAliObjectsLoader, defaultImageSrcLoader } from 'ng-zorro-antd/experimental/image';

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

@NgModule({
  ...
  providers: [
    { provide: NZ_CONFIG, useValue: ngZorroConfig }
  ]
})
export class AppModule {}

Loading...

Auto Srcset

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

Loading...

API#

nz-imagecomponent#

Property	Description	Type	Default	Global Config
nzSrc	URL	`string`	-
nzAlt	Alt	`string`	-
nzWidth	Width	`number\|string`	`auto`
nzHeight	Height	`number\|string`	`auto`
nzAutoSrcset	Whether to optimize image loading	`boolean`	`false`	✅
nzSrcLoader	Loader	`NzImageSrcLoader`	`defaultImageSrcLoader`	✅
nzPriority	Whether to add preload (only SSR)	`boolean`	`false`	✅

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.