From 3dfdb71d65ed15e7d3e69ffe3b89b7b4cef9504a Mon Sep 17 00:00:00 2001
From: SkyZeroZx <73321943+SkyZeroZx@users.noreply.github.com>
Date: Tue, 6 Jan 2026 15:20:03 -0500
Subject: [PATCH] docs: add docs for transform property in built-in loaders

---
 adev/src/content/guide/image-optimization.md  | 34 +++++++++++++++++++
 .../image_loaders/cloudflare_loader.ts        |  1 +
 .../image_loaders/cloudinary_loader.ts        |  1 +
 .../image_loaders/imagekit_loader.ts          |  1 +
 .../image_loaders/imgix_loader.ts             |  1 +
 5 files changed, 38 insertions(+)

diff --git a/adev/src/content/guide/image-optimization.md b/adev/src/content/guide/image-optimization.md
index 014f83ec3b2..d5b6c958d2c 100644
--- a/adev/src/content/guide/image-optimization.md
+++ b/adev/src/content/guide/image-optimization.md
@@ -369,6 +369,40 @@ There is an additional attribute supported by the `NgOptimizedImage` directive,
 
 A common use for `loaderParams` is controlling advanced image CDN features.
 
+### Using the `transform` property with built-in loaders
+
+The built-in loaders for Cloudinary, Cloudflare, ImageKit, and Imgix support a special `transform` property within `loaderParams`. This property allows you to apply custom image transformations provided by your CDN.
+
+The `transform` property accepts two formats:
+
+#### String format
+
+Provide transformations as a comma-separated string using your CDN's transformation syntax:
+
+```html
+<img
+  ngSrc="my-image.jpg"
+  width="400"
+  height="300"
+  [loaderParams]="{transform: 'e_grayscale,r_10'}"
+/>
+```
+
+#### Object format
+
+Provide transformations as an object with key-value pairs.
+
+```html
+<img
+  ngSrc="my-image.jpg"
+  width="400"
+  height="300"
+  [loaderParams]="{transform: {e: 'grayscale', r: 10}}"
+/>
+```
+
+NOTE: The `transform` property is not supported by the Netlify loader, as Netlify's image CDN does not provide custom transformation parameters.
+
 ### Example custom loader
 
 The following shows an example of a custom loader function. This example function concatenates `src` and `width`, and uses `loaderParams` to control a custom CDN feature for rounded corners:
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
index d29389f447f..46d6888a3ed 100644
--- 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
@@ -20,6 +20,7 @@ import {normalizeLoaderTransform} from './normalized_options';
  * @param path Your domain name, e.g. https://mysite.com
  * @returns Provider that provides an ImageLoader function
  *
+ * @see [Image Optimization Guide](guide/image-optimization)
  * @publicApi
  */
 export const provideCloudflareLoader: (path: string) => Provider[] = createImageLoader(
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
index 902316c480a..36c0d4635f9 100644
--- 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
@@ -36,6 +36,7 @@ function isCloudinaryUrl(url: string): boolean {
  * https://subdomain.mysite.com
  * @returns Set of providers to configure the Cloudinary loader.
  *
+ * @see [Image Optimization Guide](guide/image-optimization)
  * @publicApi
  */
 export const provideCloudinaryLoader: (path: string) => Provider[] = createImageLoader(
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
index 6176bd6d7a3..3250b28d019 100644
--- 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
@@ -36,6 +36,7 @@ function isImageKitUrl(url: string): boolean {
  * https://subdomain.mysite.com
  * @returns Set of providers to configure the ImageKit loader.
  *
+ * @see [Image Optimization Guide](guide/image-optimization)
  * @publicApi
  */
 export const provideImageKitLoader: (path: string) => Provider[] = createImageLoader(
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
index 7e482aa305a..53a221a92bc 100644
--- 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
@@ -34,6 +34,7 @@ function isImgixUrl(url: string): boolean {
  * e.g. https://somepath.imgix.net or https://images.mysite.com
  * @returns Set of providers to configure the Imgix loader.
  *
+ * @see [Image Optimization Guide](guide/image-optimization)
  * @publicApi
  */
 export const provideImgixLoader: (path: string) => Provider[] = createImageLoader(