feat(common): support height in ImageLoaderConfig and built-in loaders

SkyZeroZx · AndrewKushnir · commit 51cc91480761 · 2026-02-09T14:51:04.000-08:00
Introduces an optional `height` property in `ImageLoaderConfig`, allowing built-in image loaders to generate URLs with explicit height parameters. This improves layout control and enables better support for loaders that require height-based transformations. Closes #51723
diff --git a/goldens/public-api/common/index.api.md b/goldens/public-api/common/index.api.md
@@ -334,6 +334,7 @@ export type ImageLoader = (config: ImageLoaderConfig) => string;
 
 // @public
 export interface ImageLoaderConfig {
+    height?: number;
     isPlaceholder?: boolean;
     loaderParams?: {
         [key: string]: any;
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/cloudflare_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/cloudflare_loader.ts
@@ -34,6 +34,10 @@ function createCloudflareUrl(path: string, config: ImageLoaderConfig) {
     params += `,width=${config.width}`;
   }
 
+  if (config.height) {
+    params += `,height=${config.height}`;
+  }
+
   // When requesting a placeholder image we ask for a low quality image to reduce the load time.
   if (config.isPlaceholder) {
     params += `,quality=${PLACEHOLDER_QUALITY}`;
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/cloudinary_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/cloudinary_loader.ts
@@ -65,6 +65,10 @@ function createCloudinaryUrl(path: string, config: ImageLoaderConfig) {
     params += `,w_${config.width}`;
   }
 
+  if (config.height) {
+    params += `,h_${config.height}`;
+  }
+
   if (config.loaderParams?.['rounded']) {
     params += `,r_max`;
   }
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/image_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/image_loader.ts
@@ -27,6 +27,10 @@ export interface ImageLoaderConfig {
    * Width of the requested image (to be used when generating srcset).
    */
   width?: number;
+  /**
+   * Height of the requested image (to be used when generating srcset).
+   */
+  height?: number;
   /**
    * Whether the loader should generate a URL for a small image placeholder instead of a full-sized
    * image.
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/imagekit_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/imagekit_loader.ts
@@ -54,6 +54,10 @@ export function createImagekitUrl(path: string, config: ImageLoaderConfig): stri
     params.push(`w-${width}`);
   }
 
+  if (config.height) {
+    params.push(`h-${config.height}`);
+  }
+
   // When requesting a placeholder image we ask for a low quality image to reduce the load time.
   if (config.isPlaceholder) {
     params.push(`q-${PLACEHOLDER_QUALITY}`);
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/imgix_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/imgix_loader.ts
@@ -52,6 +52,10 @@ function createImgixUrl(path: string, config: ImageLoaderConfig) {
     params.push(`w=${config.width}`);
   }
 
+  if (config.height) {
+    params.push(`h=${config.height}`);
+  }
+
   // When requesting a placeholder image we ask a low quality image to reduce the load time.
   if (config.isPlaceholder) {
     params.push(`q=${PLACEHOLDER_QUALITY}`);
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/netlify_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/netlify_loader.ts
@@ -91,6 +91,10 @@ function createNetlifyUrl(config: ImageLoaderConfig, path?: string) {
     url.searchParams.set('w', config.width.toString());
   }
 
+  if (config.height) {
+    url.searchParams.set('h', config.height.toString());
+  }
+
   // When requesting a placeholder image we ask for a low quality image to reduce the load time.
   // If the quality is specified in the loader config - always use provided value.
   const configQuality = config.loaderParams?.['quality'] ?? config.loaderParams?.['q'];
diff --git a/packages/common/src/directives/ng_optimized_image/ng_optimized_image.ts b/packages/common/src/directives/ng_optimized_image/ng_optimized_image.ts
@@ -562,13 +562,29 @@ export class NgOptimizedImage implements OnInit, OnChanges {
     }
   }
 
+  /**
+   * Calculates the aspect ratio of the image based on width and height.
+   * Returns null if the aspect ratio cannot be calculated (missing dimensions or height is 0).
+   */
+  private getAspectRatio(): number | null {
+    if (this.width && this.height && this.height !== 0) {
+      return this.width / this.height;
+    }
+    return null;
+  }
+
   private callImageLoader(
     configWithoutCustomParams: Omit<ImageLoaderConfig, 'loaderParams'>,
   ): string {
     let augmentedConfig: ImageLoaderConfig = configWithoutCustomParams;
     if (this.loaderParams) {
       augmentedConfig.loaderParams = this.loaderParams;
     }
+    // Calculate height if width is provided and aspect ratio is available
+    const ratio = this.getAspectRatio();
+    if (ratio !== null && augmentedConfig.width) {
+      augmentedConfig.height = Math.round(augmentedConfig.width / ratio);
+    }
     return this.imageLoader(augmentedConfig);
   }
 
diff --git a/packages/common/test/directives/ng_optimized_image_spec.ts b/packages/common/test/directives/ng_optimized_image_spec.ts
@@ -1331,6 +1331,33 @@ describe('Image directive', () => {
       );
     });
 
+    it('should pass calculated height to placeholder loader based on aspect ratio', () => {
+      const placeholderLoaderWithHeight = (config: ImageLoaderConfig) => {
+        const widthStr = config.width ? `w=${config.width}` : '';
+        const heightStr = config.height ? `h=${config.height}` : '';
+        const phStr = config.isPlaceholder ? 'ph=true' : '';
+        const params = [widthStr, heightStr, phStr].filter((p) => p).join('&');
+        return `${IMG_BASE_URL}/${config.src}${params ? '?' + params : ''}`;
+      };
+      const imageConfig = {
+        placeholderResolution: 30,
+      };
+      setupTestingModule({imageLoader: placeholderLoaderWithHeight, imageConfig});
+      const template = '<img ngSrc="path/img.png" width="400" height="200" placeholder />';
+
+      const fixture = createTestComponent(template);
+      fixture.detectChanges();
+      const nativeElement = fixture.nativeElement as HTMLElement;
+      const img = nativeElement.querySelector('img')!;
+      const styles = parseInlineStyles(img);
+      // Aspect ratio is 400/200 = 2, placeholderResolution is 30
+      // Expected height: 30 / 2 = 15
+      // Double quotes removed to account for different browser behavior.
+      expect(styles.get('background-image')?.replace(/"/g, '')).toBe(
+        `url(${IMG_BASE_URL}/path/img.png?w=30&h=15&ph=true)`,
+      );
+    });
+
     it('should apply a background blur to images with a placeholder', () => {
       setupTestingModule({imageLoader});
       const template =
@@ -1981,6 +2008,122 @@ describe('Image directive', () => {
       );
     });
 
+    it('should pass height to custom image loader based on aspect ratio', () => {
+      const imageLoader = (config: ImageLoaderConfig) => {
+        const widthStr = config.width ? `w=${config.width}` : '';
+        const heightStr = config.height ? `h=${config.height}` : '';
+        const params = [widthStr, heightStr].filter((p) => p).join('&');
+        return `${IMG_BASE_URL}/${config.src}${params ? '?' + params : ''}`;
+      };
+      setupTestingModule({imageLoader});
+
+      const template = '<img ngSrc="img.png" width="150" height="50">';
+      const fixture = createTestComponent(template);
+      fixture.detectChanges();
+
+      const nativeElement = fixture.nativeElement as HTMLElement;
+      const img = nativeElement.querySelector('img')!;
+      // For src without width, height should not be passed
+      expect(img.src).toBe(`${IMG_BASE_URL}/img.png`);
+    });
+
+    it('should pass calculated height to custom image loader when generating srcsets', () => {
+      const imageLoader = (config: ImageLoaderConfig) => {
+        const widthStr = config.width ? `w=${config.width}` : '';
+        const heightStr = config.height ? `h=${config.height}` : '';
+        const params = [widthStr, heightStr].filter((p) => p).join('&');
+        return `${IMG_BASE_URL}/${config.src}${params ? '?' + params : ''}`;
+      };
+      setupTestingModule({imageLoader});
+
+      const template = '<img ngSrc="img.png" width="150" height="50">';
+      const fixture = createTestComponent(template);
+      fixture.detectChanges();
+
+      const nativeElement = fixture.nativeElement as HTMLElement;
+      const img = nativeElement.querySelector('img')!;
+      // Aspect ratio is 150/50 = 3, so for widths 150 and 300:
+      // height should be 50 and 100 respectively
+      expect(img.srcset).toBe(
+        `${IMG_BASE_URL}/img.png?w=150&h=50 1x, ${IMG_BASE_URL}/img.png?w=300&h=100 2x`,
+      );
+    });
+
+    it('should pass calculated height to custom image loader when generating responsive srcsets', () => {
+      const imageLoader = (config: ImageLoaderConfig) => {
+        const widthStr = config.width ? `w=${config.width}` : '';
+        const heightStr = config.height ? `h=${config.height}` : '';
+        const params = [widthStr, heightStr].filter((p) => p).join('&');
+        return `${IMG_BASE_URL}/${config.src}${params ? '?' + params : ''}`;
+      };
+      setupTestingModule({imageLoader});
+
+      const template = '<img ngSrc="img.png" width="150" height="50" sizes="100vw">';
+      const fixture = createTestComponent(template);
+      fixture.detectChanges();
+
+      const nativeElement = fixture.nativeElement as HTMLElement;
+      const img = nativeElement.querySelector('img')!;
+      // Aspect ratio is 150/50 = 3
+      // Expected heights: 640/3=213, 750/3=250, etc.
+      expect(img.srcset).toBe(
+        `${IMG_BASE_URL}/img.png?w=640&h=213 640w, ${IMG_BASE_URL}/img.png?w=750&h=250 750w, ${IMG_BASE_URL}/img.png?w=828&h=276 828w, ${IMG_BASE_URL}/img.png?w=1080&h=360 1080w, ${IMG_BASE_URL}/img.png?w=1200&h=400 1200w, ${IMG_BASE_URL}/img.png?w=1920&h=640 1920w, ${IMG_BASE_URL}/img.png?w=2048&h=683 2048w, ${IMG_BASE_URL}/img.png?w=3840&h=1280 3840w`,
+      );
+    });
+
+    it('should not pass height to custom image loader when height is not provided', () => {
+      const imageLoader = (config: ImageLoaderConfig) => {
+        const widthStr = config.width ? `w=${config.width}` : '';
+        const heightStr = config.height ? `h=${config.height}` : '';
+        const params = [widthStr, heightStr].filter((p) => p).join('&');
+        return `${IMG_BASE_URL}/${config.src}${params ? '?' + params : ''}`;
+      };
+      setupTestingModule({imageLoader});
+
+      const template = '<img ngSrc="img.png" fill>';
+      const fixture = createTestComponent(template);
+      fixture.detectChanges();
+
+      const nativeElement = fixture.nativeElement as HTMLElement;
+      const img = nativeElement.querySelector('img')!;
+      // No height provided (fill mode), so aspect ratio cannot be calculated
+      // In fill mode, a responsive srcset is generated but without height parameters
+      expect(img.srcset).toBe(
+        `${IMG_BASE_URL}/img.png?w=640 640w, ${IMG_BASE_URL}/img.png?w=750 750w, ${IMG_BASE_URL}/img.png?w=828 828w, ${IMG_BASE_URL}/img.png?w=1080 1080w, ${IMG_BASE_URL}/img.png?w=1200 1200w, ${IMG_BASE_URL}/img.png?w=1920 1920w, ${IMG_BASE_URL}/img.png?w=2048 2048w, ${IMG_BASE_URL}/img.png?w=3840 3840w`,
+      );
+    });
+
+    it('should pass height to custom image loaders', () => {
+      @Component({
+        selector: 'test-cmp',
+        standalone: false,
+        template: `<img [ngSrc]="ngSrc" width="300" height="150" sizes="100vw" />`,
+      })
+      class TestComponent {
+        ngSrc = `img.png`;
+      }
+      const imageLoader = (config: ImageLoaderConfig) => {
+        const params: string[] = [];
+        if (config.width) {
+          params.push(`w=${config.width}`);
+        }
+        if (config.height) {
+          params.push(`h=${config.height}`);
+        }
+        const query = params.length ? `?${params.join('&')}` : '';
+        return `${IMG_BASE_URL}/${config.src}${query}`;
+      };
+      setupTestingModule({imageLoader, component: TestComponent});
+      const fixture = TestBed.createComponent(TestComponent);
+      fixture.detectChanges();
+
+      let nativeElement = fixture.nativeElement as HTMLElement;
+      let imgs = nativeElement.querySelectorAll('img')!;
+      expect(imgs[0].getAttribute('srcset')).toBe(
+        `${IMG_BASE_URL}/img.png?w=640&h=320 640w, ${IMG_BASE_URL}/img.png?w=750&h=375 750w, ${IMG_BASE_URL}/img.png?w=828&h=414 828w, ${IMG_BASE_URL}/img.png?w=1080&h=540 1080w, ${IMG_BASE_URL}/img.png?w=1200&h=600 1200w, ${IMG_BASE_URL}/img.png?w=1920&h=960 1920w, ${IMG_BASE_URL}/img.png?w=2048&h=1024 2048w, ${IMG_BASE_URL}/img.png?w=3840&h=1920 3840w`,
+      );
+    });
+
     it('should set `src` to an image URL that does not include a default width parameter', () => {
       const imageLoader = (config: ImageLoaderConfig) => {
         const widthStr = config.width ? `?w=${config.width}` : ``;

Original file line number	Diff line number	Diff line change
`@@ -65,6 +65,10 @@ function createCloudinaryUrl(path: string, config: ImageLoaderConfig) {`
`65`	`65`	params += `,w_${config.width}`;
`66`	`66`	`}`
`67`	`67`
	`68`	`+ if (config.height) {`
	`69`	+ params += `,h_${config.height}`;
	`70`	`+ }`
	`71`	`+`
`68`	`72`	`if (config.loaderParams?.['rounded']) {`
`69`	`73`	params += `,r_max`;
`70`	`74`	`}`