diff --git a/src/assets/images/images/custom-flow.png b/src/assets/images/images/custom-flow.png new file mode 100644 index 00000000000..d28560fe4b7 Binary files /dev/null and b/src/assets/images/images/custom-flow.png differ diff --git a/src/content/docs/images/index.mdx b/src/content/docs/images/index.mdx index 0e34b2400a6..a00cc547b2c 100644 --- a/src/content/docs/images/index.mdx +++ b/src/content/docs/images/index.mdx @@ -67,6 +67,10 @@ If you’re new to Images, start here to learn the essentials: Browse the various features for compressing, cropping, resizing, and manipulating images. + + Create transformation flows to configure automated rules for optimizing remote images on your zone. + + + + + dpr=1 output + + + dpr=2 output + + + + + width=300,height=200,dpr=1 + + + width=300,height=200,dpr=2 + + + + +## Use the `srcset` attribute + +When you embed an image using an `` element, you can use its [`srcset`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute to give the browser a list of the same image at different sizes. + +The browser evaluates screen size, pixel density, and network conditions, then selects the single best match. + +The snippet below shows how `srcset` can be used within an `` tag to serve one of two possible sizes, depending on the user's device pixel ratio: ```html ``` -In the URL path used in this example, the `src` attribute is for images with the usual "1x" density. `/cdn-cgi/image/` is a special path for resizing images. This is followed by `width=960` which resizes the image to have a width of 960 pixels. `/assets/product.jpg` is a URL to the source image on the server. +Instead of pre-generating each size, use Images to point every `srcset` entry at the same source image with a different `width` parameter and pixel density descriptor (for example, `2x`). Once the browser selects the right width for the user's device pixel ratio, Cloudflare dynamically generates the resized version on request: -The `srcset` attribute adds another, high-DPI image. The browser will automatically select between the images in the `src` and `srcset`. In this case, specifying `width=1920` (two times 960 pixels) and adding `2x` at the end, informs the browser that this is a double-density image. It will be displayed at the same size as a 960 pixel image, but with double the number of pixels which will make it look twice as sharp on high-DPI displays. +```html + +``` -Note that it does not make sense to scale images up for use in `srcset`. That would only increase file sizes without improving visual quality. The source images you should use with `srcset` must be high resolution, so that they are only scaled down for `1x` displays, and displayed as-is or also scaled down for `2x` displays. +In the example above, the `src` attribute contains the image for 1x displays (for example, HD/1080p monitors). The `srcset` attribute adds a larger, high-DPI image for 2x displays (for example, most mobile devices, 4K desktop displays). Use high-resolution source images, as scaling a low-resolution image increases file size without improving quality. -### `srcset` for responsive images +### Create responsive layouts -When you want to display an image that takes a certain percentage of the window or screen width, the image should have dimensions that are appropriate for a visitor’s screen size. Screen sizes vary a lot, typically from 320 pixels to 3840 pixels, so there is not a single image size that fits all cases. With `` you can offer the browser several possible sizes and let it choose the most appropriate size automatically. +Pixel density descriptors are used when the image has a fixed CSS size (e.g. a 960px product photo) and the viewport width doesn't matter. Here, you know exactly how many CSS pixels the image will be, and you want to provide higher-resolution versions for high-DPI screens. -By default, the browser assumes the image will be stretched to the full width of the screen, and will pick a size that is closest to a visitor’s screen size. In the `src` attribute the browser will pick any size that is a good fallback for older browsers that do not understand `srcset`. +However, if the image scales with the viewport — that is, its CSS size changes based on the screen width (for example, `width: 100%`, `width: 50vw`) — then use the width descriptor (`w`) instead to provide a range of widths: ```html ``` -In the previous case, the number followed by `x` described _screen_ density. In this case the number followed by `w` describes the _image_ size. There is no need to specify screen density here (`2x`, etc.), because the browser automatically takes it into account and picks a higher-resolution image when necessary. - -If the image is not displayed at full width of the screen (or browser window), you have two options: +The `w` values tell the browser the pixel width of each option. The browser factors in both viewport width and display density to choose the best match. -- If the image is displayed at full width of a fixed-width column, use the first technique that uses one specific image size. -- If it takes a specific percentage of the screen, or stretches to full width only sometimes (using CSS media queries), then add the `sizes` attribute as described below. +#### Use the `sizes` attribute -#### The `sizes` attribute - -If the image takes 50% of the screen (or window) width: +By default, the browser assumes the image fills the full viewport. If the image only occupies part of the screen, then you can use `sizes` to tell the browser how wide it actually is: ```html - + + ``` -The `vw` unit is a percentage of the viewport (screen or window) width. If the image can have a different size depending on media queries or other CSS properties, such as `max-width`, then specify all the conditions in the `sizes` attribute: +If the image can have a different size depending on media queries or other CSS properties (for example, `max-width`), then specify all the conditions in the `sizes` attribute: ```html ``` -In this example, `sizes` says that for screens smaller than 640 pixels the image is displayed at full viewport width; on all larger screens the image stays at 640px. Note that one of the options in `srcset` is 1280 pixels, because an image displayed at 640 CSS pixels may need twice as many image pixels on a high-dpi (`2x`) display. +In the example above: -## WebP images +- If the screen size is below 640px, then the image fills the entire viewport. +- If the screen size is above 640px, then the image scales with the viewport and caps at 640px. +- On a 2x display above 640px, the browser needs 1280 physical pixels to fill the 640px layout width, so it selects the 1280w entry. -`srcset` is useful for pixel-based formats such as PNG, JPEG, and WebP. It is unnecessary for vector-based SVG images. +## Use `width=auto` -HTML also [supports the `` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture) that can optionally request an image in the WebP format, but you do not need it. Cloudflare can serve WebP images automatically whenever you use `/cdn-cgi/image/format=auto` URLs in `src` or `srcset`. +With `srcset`, you control exactly which sizes are available, which requires updating your HTML for every image. -If you want to use WebP images, but do not need resizing, you have two options: +On the other hand, `width=auto` takes a different approach, where Cloudflare determines the right width for each request from a single URL: -- You can enable the automatic [WebP conversion in Polish](/images/polish/activate-polish/). This will convert all images on the site. -- Alternatively, you can change specific image paths on the site to start with `/cdn-cgi/image/format=auto/`. For example, change `https://example.com/assets/hero.jpg` to `https://example.com/cdn-cgi/image/format=auto/assets/hero.jpg`. +```html +/cdn-cgi/image/width=auto/assets/hero.jpg +``` -## Transform with `width` parameter +This is especially useful when optimizing remote images with [transformation flows](/images/optimization/transformations/flows/), where you can apply `width=auto` across your entire zone without modifying any markup. -When setting up a [transformation URL](/images/optimization/features/#width), you can apply the `width=auto` option to serve the most optimal image based on the available information about the user's browser and device. +When a request includes `width=auto`, Cloudflare determines the width based on screen size using client hints, if sent, or user-agent detection as a fallback. -This method can serve multiple sizes from a single URL. Currently, images will be served in one of four sizes: +### Client hints (preferred) -- 1200 (large desktop/monitor) -- 960 (desktop) -- 768 (tablet) -- 320 (mobile) +Browsers that support client hints (Chrome, Edge, Opera) send the viewport width in a request header. Then, Cloudflare reads this value and selects the right image size. -Each width is counted as a separate transformation. For example, if you use `width=auto` and the image is delivered with a width of 320px to one user and 960px to another user, then this counts as two unique transformations. +Rather than generating a unique image for every possible viewport width, Cloudflare snaps to the smallest breakpoint that is equal to or greater than the detected screen width. -By default, this feature uses information from the user agent, which detects the platform type (for example, iOS or Android) and browser. +The default breakpoints for client hints are: `320`, `768`, `960`, and `1200` pixels. -### Client hints +The following table shows the widths that Cloudflare will pick based on the default breakpoints. If the detected viewport width exceeds the largest breakpoint, the image is served at that largest breakpoint. -For more accurate results, you can use client hints to send the user's browser information as request headers. +| Detected viewport width | Served image width | +| ---------- | ------------- | +| 280px | 320px | +| 500px | 768px | +| 960px | 960px | +| 1500px | 1200px | -This method currently works only on Chromium-based browsers such as Chrome, Edge, and Opera. +You can override the default breakpoints using the [`wbreakpoints`](/images/optimization/features/#width) sub-parameter, which accepts positive integers separated by semicolons. -You can enable client hints via HTML by adding the following tag in the `` tag of your page before any other elements: +#### Enabling client hints -```txt - +Client hints give Cloudflare the most accurate information, but require opt-in from your site. Without them, `width=auto` falls back to user-agent detection. + +You can enable client hints using one of the following methods: + +**HTML `` tag** + +Add the following in the `` of your page before any other elements: + +```html + ``` -Replace `https://example.com` with your Cloudflare zone where transformations are enabled. +**HTTP response headers** -Alternatively, you can enable client hints via HTTP by adding the following headers to your HTML page's response: +Add these headers to your HTML response: ```txt critical-ch: sec-ch-viewport-width, sec-ch-dpr - -permissions-policy: ch-dpr=("https://example.com"), ch-viewport-width=("https://example.com") +permissions-policy: ch-dpr=("{ZONE}"), ch-viewport-width=("{ZONE}") ``` -Replace `https://example.com` with your Cloudflare zone where transformations are enabled. +### User-agent detection (fallback) + +When client hints are not available, Cloudflare classifies the device as mobile or desktop based on the user-agent string and selects the corresponding size. + +The default sizes for user-agent detection are: + +| Device type | Default size | +| -------------------------------------------- | ------------ | +| Mobile (`iPhone` or `Android` in user-agent) | 768px | +| Desktop (all other user-agents) | 1200px | + +You can override the default sizes using the [`wmobile` and `wdesktop`](/images/optimization/features/#width) sub-parameters, which accept positive integers. diff --git a/src/content/docs/images/optimization/transformations/bindings.mdx b/src/content/docs/images/optimization/transformations/bindings.mdx index af140916067..2c3eea3ba26 100644 --- a/src/content/docs/images/optimization/transformations/bindings.mdx +++ b/src/content/docs/images/optimization/transformations/bindings.mdx @@ -3,7 +3,7 @@ pcx_content_type: how-to title: Bind to Workers API description: Bind the Cloudflare Images API to a Worker to transform images without requiring a public URL. sidebar: - order: 4 + order: 5 products: - images - workers diff --git a/src/content/docs/images/optimization/transformations/control-origin-access.mdx b/src/content/docs/images/optimization/transformations/control-origin-access.mdx index 9cf3ae8aa46..f4d7a0ff90c 100644 --- a/src/content/docs/images/optimization/transformations/control-origin-access.mdx +++ b/src/content/docs/images/optimization/transformations/control-origin-access.mdx @@ -3,7 +3,7 @@ pcx_content_type: reference title: Control origin access description: Hide original image sources and restrict access using Cloudflare Workers with image transformations. sidebar: - order: 5 + order: 6 products: - images - workers diff --git a/src/content/docs/images/optimization/transformations/draw-overlays.mdx b/src/content/docs/images/optimization/transformations/draw-overlays.mdx index dea1a91c057..b9283fd4ad2 100644 --- a/src/content/docs/images/optimization/transformations/draw-overlays.mdx +++ b/src/content/docs/images/optimization/transformations/draw-overlays.mdx @@ -3,7 +3,7 @@ pcx_content_type: reference title: Draw overlays and watermarks description: Add watermarks, logos, and overlay images on top of transformed images using Cloudflare Workers. sidebar: - order: 6 + order: 7 products: - images - workers diff --git a/src/content/docs/images/optimization/transformations/flows.mdx b/src/content/docs/images/optimization/transformations/flows.mdx new file mode 100644 index 00000000000..90b4c423f90 --- /dev/null +++ b/src/content/docs/images/optimization/transformations/flows.mdx @@ -0,0 +1,135 @@ +--- +pcx_content_type: reference +title: Create transformation flows +sidebar: + order: 3 + products: + - images +--- +import { Description, Render } from "~/components"; + + + Define automated rules to optimize remote images without writing any code or changing your existing URLs. + + +Flows let you automatically apply image optimization to requests on your zone. + +Each flow pairs a set of conditional triggers (for example, image is a JPEG or PNG) with optimization parameters (for example, transcode to AVIF). + +When an image request matches a flow, Cloudflare transparently rewrites it through the Images service and serves the optimized result. + +## Types of flows + +You can use pre-built flows to handle migrations from other image optimization services (like Fastly) or create your own custom flows. + +A **provider flow** is a translation layer that maps image URLs from another image optimization service to Cloudflare. Your existing URLs — including provider-specific parameters — continue to work without any changes. + +Currently, Cloudflare supports flows for Fastly Image Optimizer. When enabled, Cloudflare automatically translates Fastly's parameters to their Cloudflare equivalents. For example: + +- Fastly's `brightness` parameter accepts a range from `-100` to `100`, while Cloudflare's `brightness` works as a multiplier. The value is scaled accordingly. +- Fastly's `orient` parameter is mapped to Cloudflare's `flip` and `rotate` parameters. + +A **custom flow** lets you define your own conditions and actions for image optimization. + +This is well-suited for situations where you want to optimize your images broadly and consistently, such as: +- **Automatic format conversion** — Transcode all images to modern formats like AVIF or WebP across your entire site. +- **Responsive sizing** — Automatically resize images based on each user's device. +- **Directory-based optimization** — Enforce a consistent size for all images in a particular path, such as 100x100 for images where the path contains `/thumbnail`. + +## How flows work + +Before setting up a flow, make sure that transformations are turned on for your zone under **Images** > **Transformations** in the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/images/transformations). + +When an image is requested on your zone, Cloudflare checks to see whether the request matches the conditions for any of your configured flows: +- Flows are evaluated from top to bottom in the order that they appear in the dashboard. +- If a request matches more than one flow, only the first matching flow will run. +- If no flow matches, then the request passes through to your origin unmodified. +- To control priority, you can reorder flows in the dashboard. + +If the request matches a flow's conditions, then Cloudflare rewrites the URL to pass through the Images service with the specified parameters: +- A custom flow triggers only on requests for [supported image extensions](/images/get-started/limits/). HTML pages, CSS files, and other non-images are never affected. +- A provider flow evaluates requests based on provider-specific optimization parameters. For example, a Fastly provider flow triggers only when the request contains parameters like `?width`, `?height`, or `?fit`. Cloudflare will ignore any unrecognized parameters. + +In your request lifecycle, flows are evaluated after standard HTTP [redirect rules](/rules/url-forwarding/): +- Any existing URL rewrites or redirect rules will be applied before Images evaluates the request, which may affect matching behavior. +- Flows include built-in loop prevention. If the request is already coming from the Images service, then the flow will not re-trigger on that subrequest. + +## Set up a provider flow + +Currently, Cloudflare supports flows to handle migrations from Fastly Image Optimizer. + +To add a provider flow: +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account. +2. Go to **Images** > **Transformations** and select your zone. +3. Select the **Automation** tab, then select **Add provider flow**. +4. Choose **Fastly** as the provider. +5. **Save** your flow. + +## Set up a custom flow + +### 1. Create a new flow + +In the Cloudflare dashboard, go to [**Images** > **Transformations**](https://dash.cloudflare.com/?to=/:account/images/transformations) and select the zone where you want to set up the custom flow. + +Go to the **Automation** tab and select **Add custom flow** to open the side panel where you can configure your flow. + +![Custom flow configuration panel](~/assets/images/images/custom-flow.png) + +### 2. Configure the conditions + +A custom flow is triggered when an incoming request matches all of the configured conditions in the flow: + +- **File extension** — Match requests for all image formats or only specific file extensions, such as JPEG, PNG, or WebP. +- **URL path** — Match requests where the URL path matches a specified pattern, such as `/images/*` or `/assets/thumbnails/*`. +- **Query parameter** — Match requests where the query string contains a specified parameter, such as `orient`. + +### 3. Configure the actions + +Next, define the optimization parameters that should be applied when the flow is triggered. + +You can apply multiple actions within a single flow. For the full list of available parameters, refer to [Features](/images/optimization/features/). + +The key parameters for most use cases are: + +#### `format` | `f` + +Set `format=auto` to automatically serve images in the most efficient format (e.g. AVIF, WebP) for each requesting browser. + +If the browser doesn't support AVIF, then Cloudflare will fall back to WebP or a standard format. + +Refer to [`format`](/images/optimization/features/#format) + +#### `quality` | `q` + +Control the compression quality of the output image. Accepts either: + +- A **fixed value** from `1` (low quality, small file size) to `100` (high quality, large file size). +- A **perceptual quality level**: `high`, `medium-high`, `medium-low`, or `low`. + +Refer to [`quality`](/images/optimization/features/#quality) + +#### `slow-connection-quality` | `scq` + +Override `quality` when a slow connection is detected via client hints. Accepts the same fixed or perceptual values as `quality`. This serves lower-quality (and smaller) images to users on slow networks without affecting users on fast connections. + +Refer to [`slow-connection-quality`](/images/optimization/features/#slow-connection-quality) + +#### `width` | `w` + +Set [`width=auto`](/images/optimization/features/#width) to automatically size images based on the requesting device. + +Cloudflare determines the optimal width using either [client hints](/images/optimization/make-responsive-images/#client-hints-preferred) (sent by the browser) or user-agent detection as a fallback. + +You can fine-tune the `width=auto` behavior with the following sub-parameters: + +| Sub-parameter | Description | Default | +| --- | --- | --- | +| `wbreakpoints` | Override default breakpoint widths, in pixels (client hints) | `320;768;960;1200` | +| `wmobile` | Override default width, in pixels, for mobile devices (user-agent detection) | `768` | +| `wdesktop` | Override default width, in pixels, for desktop devices (user-agent detection) | `1200` | + +To learn how `width=auto` works, refer to our guide on [serving responsive images](/images/optimization/make-responsive-images/). + +### 4. Publish your flow + +Select **Save** on the side panel to add your custom flow, then select **Save** on your list of flows to turn on your flow. diff --git a/src/content/docs/images/optimization/transformations/overview.mdx b/src/content/docs/images/optimization/transformations/overview.mdx index deeab382c8b..d623c6694db 100644 --- a/src/content/docs/images/optimization/transformations/overview.mdx +++ b/src/content/docs/images/optimization/transformations/overview.mdx @@ -41,5 +41,6 @@ Each unique combination of source image and parameters is cached and billed sepa After enabling transformations on your zone, you can configure how Cloudflare handles transformation requests: - **[Define source origins](/images/optimization/transformations/sources)** — Specify which origins Cloudflare can pull source images from. By default, Cloudflare only accepts source images from the same zone where transformations are served. +- **[Create transformation flows](/images/optimization/transformations/flows)** — Set up automated rules that apply image optimization to matching requests without requiring URL changes or custom code. - **[Control origin access](/images/optimization/transformations/control-origin-access)** — Use Workers to add custom logic for validating and controlling access to source images. - **[Set up rewrite rules](/images/optimization/transformations/rewrite-rules)** — Use Transform Rules to rewrite image URLs and serve transformations from custom paths. diff --git a/src/content/docs/images/optimization/transformations/preserve-content-credentials.mdx b/src/content/docs/images/optimization/transformations/preserve-content-credentials.mdx index 392b83f5206..002a54b3d34 100644 --- a/src/content/docs/images/optimization/transformations/preserve-content-credentials.mdx +++ b/src/content/docs/images/optimization/transformations/preserve-content-credentials.mdx @@ -3,7 +3,7 @@ pcx_content_type: reference title: Preserve Content Credentials description: Retain C2PA metadata and provenance data when transforming remote images with Cloudflare Images. sidebar: - order: 7 + order: 10 products: - images --- diff --git a/src/content/docs/images/optimization/transformations/transform-via-workers.mdx b/src/content/docs/images/optimization/transformations/transform-via-workers.mdx index aac7145cd29..1a12669ad66 100644 --- a/src/content/docs/images/optimization/transformations/transform-via-workers.mdx +++ b/src/content/docs/images/optimization/transformations/transform-via-workers.mdx @@ -3,7 +3,7 @@ pcx_content_type: how-to title: Transform via Workers description: Use Cloudflare Workers to programmatically resize, format, and optimize images with custom URL schemes. sidebar: - order: 3 + order: 4 products: - images - workers diff --git a/src/content/partials/images/dpr.mdx b/src/content/partials/images/dpr.mdx index 8aef41a2af1..51029ab40f6 100644 --- a/src/content/partials/images/dpr.mdx +++ b/src/content/partials/images/dpr.mdx @@ -9,7 +9,7 @@ import dpr2Img from "~/assets/images/images/examples/dpr-2.jpg"; Scales the output resolution by a multiplier to match a user's specific screen density (for example, Retina or 4K). The default is `1`, which delivers the image at the exact width and height requested. The maximum supported value is `2`. -Modern devices have more physical pixels than CSS pixels. If you serve a 300 px image in a 300 px container on a high-DPR smartphone, then it will look blurry. Using `dpr=2` tells Cloudflare to send a 600 px image for the same 300 px container, which results in a clearer, crisper image. +Modern devices have more physical pixels than CSS pixels. If you serve a 300px image in a 300px container on a high-DPR smartphone, then it will look blurry. Using `dpr=2` tells Cloudflare to send a 600px image for the same 300px container, which results in a clearer, crisper image. The `dpr` parameter can be used with `srcset` to [serve responsive images](/images/optimization/make-responsive-images/). diff --git a/src/content/partials/images/fit.mdx b/src/content/partials/images/fit.mdx index b792f3d8c3e..1acb267548f 100644 --- a/src/content/partials/images/fit.mdx +++ b/src/content/partials/images/fit.mdx @@ -16,34 +16,38 @@ import squeezePete from "~/assets/images/images/examples/fit/pete-squeeze.jpg"; Specifies how the image is fit to the target area. -Fit is performed after setting the [`width`](/images/optimization/features/#width) and [`height`](/images/optimization/features/#height) dimensions of the image. +Fit is performed after setting the [`width`](#width) and [`height`](#height) dimensions of the image. | Option | Result | Match original aspect ratio | Upscales | | --- | --- | --- | --- | -| `contain` (default) | Show entire image without cropping | Yes | Yes | +| `scale-down` (default) | Show entire image without cropping or upscaling | Yes | No | +| `contain` | Show entire image without cropping | Yes | Yes | | `cover` | Fill the entire requested area, cropping if needed | No | Yes | -| `crop` | Same as `cover`, but never upscales | No | No | +| `crop` | Fill the entire requested area, but never upscales | No | No | | `pad` | Fit within the target area, adding space for remaining area | Yes | Yes | -| `scale-down` | Same as `contain`, but never upscales | Yes | No | | `squeeze` | Scale to exact dimensions, distorting if needed | No | Yes | ```txt - fit=scale-down + fit=pad ``` ```js - cf: {image: {fit: "scale-down"}} + cf: {image: {fit: "pad"}} ``` -#### `contain` -Resizes the image to be as large as possible within the target `width` and `height` dimensions while preserving its original aspect ratio. This is the default `fit` behavior. +#### `scale-down` +Resizes the image to fit within the specified dimensions while preserving its original aspect ratio, but never upscales the image. This is the default `fit` behavior. + +When the original image is smaller than the target area, it is returned at its original dimensions. For example, a request to serve a 1080x720 image at 2000x2000 will return the image at 1080x720. -In the example below, the 1080x720 image is resized to fit within the target 500x500 area. Since `contain` preserves original aspect ratio (3:2), the final dimensions of the output image are 500x333. +When larger, it downscales the image to fit the target area while matching the original aspect ratio. + +In the example below, the 1080x720 image is resized to fit within the target 500x500 area. Since `scale-down` preserves the original aspect ratio (3:2), the final dimensions of the output image are 500x333. @@ -54,7 +58,7 @@ In the example below, the 1080x720 image is resized to fit within the target 500 target area @@ -73,12 +77,17 @@ In the example below, the 1080x720 image is resized to fit within the target 500
- fit=contain output + fit=scale-down output
-When the original image is smaller than the target area, it upscales instead, which may reduce image quality. To avoid upscaling, use `scale-down`. +#### `contain` +Resizes the image to be as large as possible within the target `width` and `height` dimensions while preserving its original aspect ratio. + +When the original image is larger than the target area, it downscales to fit the target area (like `scale-down`). + +When smaller, it upscales instead, which may reduce image quality. To avoid upscaling, use `scale-down`. #### `cover` Fills the entire target area, shrinking or enlarging the image if needed. The output area always matches the requested `width` and `height` dimensions exactly. -When the original and target aspect ratios differ, the image is resized to cover the full target area and any overflow is cropped. Use the [`gravity`](/images/optimization/features/#gravity) parameter to control which part of the image is preserved during cropping. +When the original and target aspect ratios differ, the image is resized to cover the full target area and any overflow is cropped. Use the [`gravity`](#gravity) parameter to control which part of the image is preserved during cropping. In the example below, the 1080×720 image is first resized to 750×500 (matching the requested height) to fit the target area, then cropped from the left and right edges to its final 500x500 dimensions. @@ -115,7 +124,7 @@ When the original image is smaller than the target area, it upscales instead. To #### `crop` Resizes the image to fill the target area without upscaling. -When the original image is smaller than the target area, it is returned at its original dimensions and does not upscale. +When the original image is smaller than the target area, it keeps its original size and aspect ratio (like `scale-down`). In the example below, the original image (1080x720) is smaller than the target area (1296x1296), so it preserves its original size and aspect ratio. @@ -184,15 +193,10 @@ In the example below, the original image (1080x720) is smaller than the target a -#### `scale-down` -Resizes the image to fit within the specified dimensions while preserving its original aspect ratio, but never upscales the image. - -When the original image is smaller than the target area, it behaves like `crop` (keeps original size and aspect ratio). When larger, it behaves like `contain` (downscaled to fill the target area). - #### `squeeze` Resizes the image to exactly match the requested width and height, without cropping the edges or constraining the portions. -When the original and target aspect ratios differ, the image will be distorted to fit the target area. +When the original and target aspect ratios differ, the image will be distorted to fit the target area. @@ -234,4 +238,4 @@ When the original and target aspect ratios differ, the image will be distorted t 1080 x 540 -
\ No newline at end of file + diff --git a/src/content/partials/images/slow-connection-quality.mdx b/src/content/partials/images/slow-connection-quality.mdx index 2039720617c..d30330dc112 100644 --- a/src/content/partials/images/slow-connection-quality.mdx +++ b/src/content/partials/images/slow-connection-quality.mdx @@ -8,7 +8,7 @@ import { Tabs, TabItem} from "~/components"; ### `slow-connection-quality` | `scq` -Overrides the `quality` value whenever a slow connection is detected. Accepts the same fixed or perceptual settings as [quality](/images/optimization/features/#quality). The default is none. +Overrides the `quality` value whenever a slow connection is detected. Accepts the same fixed or perceptual settings as [quality](#quality). The default is none. :::note This feature is available only when optimizing through the URL interface on Chromium-based browsers such as Chrome, Edge, and Opera. diff --git a/src/content/partials/images/trim.mdx b/src/content/partials/images/trim.mdx index ca8d95307d8..8be4232953d 100644 --- a/src/content/partials/images/trim.mdx +++ b/src/content/partials/images/trim.mdx @@ -9,7 +9,7 @@ Removes pixels around the sides of an image. This feature can be used to trim an image by its border colors or by a specified number of pixels from its side(s). -Trim takes into account the [`dpr`](/images/optimization/features/#dpr) parameter and is performed before resizing and rotation. +Trim takes into account the [`dpr`](#dpr) parameter and is performed before resizing and rotation. #### `border` diff --git a/src/content/partials/images/width.mdx b/src/content/partials/images/width.mdx index 100ebd36981..00f52156cb6 100644 --- a/src/content/partials/images/width.mdx +++ b/src/content/partials/images/width.mdx @@ -14,7 +14,7 @@ When `width` is set, the exact behavior depends on the `fit` parameter. Accepts the following values: - A number in pixels (for example, `250`). -- `auto` — Automatically serves the image in the most optimal width based on available information about the browser and device. This method is supported only by Chromium browsers. For more information, refer to [Transform width parameter](/images/optimization/make-responsive-images/#transform-with-width-parameter). +- `auto` — Automatically serves the image in the most optimal width based on available information about the browser and device. Accepts `wbreakpoints` (client hints), `wmobile` (user-agent detection), and `wdesktop` (user-agent detection) as sub-parameters. @@ -30,6 +30,32 @@ Accepts the following values: -Ideally, image sizes should match the exact dimensions at which they are displayed on the page. If the page contains thumbnails with markup such as ``, then you can resize the image by applying `width=200`. +#### `width=auto` sub-parameters -[To serve responsive images](/images/optimization/make-responsive-images/#transform-with-html-srcset), you can use the HTML `srcset` element and apply width parameters. +When `width=auto` is specified, Cloudflare resizes the image using information from client hints (sent by the browser) or by user-agent detection as a fallback. + +You can customize the `width=auto` behavior with the following sub-parameters: + +| Sub-parameter | Description | Default | +| --- | --- | --- | +| `wbreakpoints` | Override default breakpoint widths, in pixels (client hints) | `320;768;960;1200` | +| `wmobile` | Override default width, in pixels, for mobile devices (user-agent detection) | `768` | +| `wdesktop` | Override default width, in pixels, for desktop devices (user-agent detection) | `1200` | + +When optimizing remote images with `width=auto`, each unique width counts as a separate [billable transformation](/images/pricing/#images-transformed). + +To learn how `width=auto` works, refer to our guide on [serving responsive images](/images/optimization/make-responsive-images/). + + + + ```txt + wbreakpoints=320;768;960;1920 // Changes the largest breakpoint to 1920 pixels + wbreakpoints=320;768;960;1200;1920 // Adds another breakpoint at 1920 pixels + ``` + + + ```js + cf: {image: {wbreakpoints: "320;768;960;1920"}} + ``` + + \ No newline at end of file