Unverified Commit 7b9630f8 authored by Steven's avatar Steven Committed by GitHub

chore(docs): add docs for input image formats with next/image (#71565)

This PR adds missing documentation for the supported src image types.

The input format support is determined my `sharp` and can be found here:
https://sharp.pixelplumbing.com/api-constructor
parent f260aad2
......@@ -89,7 +89,11 @@ Must be one of the following:
- A [statically imported](/docs/app/building-your-application/optimizing/images#local-images) image file
- A path string. This can be either an absolute external URL, or an internal path depending on the [loader](#loader) prop.
When using an external URL, you must add it to [remotePatterns](#remotepatterns) in `next.config.js`.
When using the default [loader](#loader), also consider the following for source images:
- When src is an external URL, you must also configure [remotePatterns](#remotepatterns)
- When src is [animated](#animated-images) or not a known format (JPEG, PNG, WebP, AVIF, GIF, TIFF) the image will be served as-is
- When src is SVG format, it will be blocked unless [`unoptimized`](#unoptimized)` or [`dangerouslyAllowSVG`](#dangerouslyallowsvg) is enabled
### `width`
......@@ -678,9 +682,9 @@ module.exports = {
### `formats`
The default [Image Optimization API](#loader) will automatically detect the browser's supported image formats via the request's `Accept` header.
The default [Image Optimization API](#loader) will automatically detect the browser's supported image formats via the request's `Accept` header in order to determine the best output format.
If the `Accept` head matches more than one of the configured formats, the first match in the array is used. Therefore, the array order matters. If there is no match (or the source image is [animated](#animated-images)), the Image Optimization API will fallback to the original image's format.
If the `Accept` header matches more than one of the configured formats, the first match in the array is used. Therefore, the array order matters. If there is no match (or the source image is [animated](#animated-images)), the Image Optimization API will fallback to the original image's format.
If no configuration is provided, the default below is used.
......@@ -692,7 +696,7 @@ module.exports = {
}
```
You can enable AVIF support with the following configuration.
You can enable AVIF support and still fallback to WebP with the following configuration.
```js filename="next.config.js"
module.exports = {
......@@ -704,7 +708,7 @@ module.exports = {
> **Good to know**:
>
> - AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
> - AVIF generally takes 50% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
> - If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the `Accept` header.
## Caching Behavior
......
......@@ -41,7 +41,11 @@ Must be one of the following:
- A [statically imported](/docs/pages/building-your-application/optimizing/images#local-images) image file
- A path string. This can be either an absolute external URL, or an internal path depending on the [loader](#loader) prop or [loader configuration](#loader-configuration).
When using an external URL, you must add it to [remotePatterns](#remote-patterns) in `next.config.js`.
When using the default [loader](#loader), also consider the following for source images:
- When src is an external URL, you must also configure [remotePatterns](#remote-patterns)
- When src is [animated](#animated-images) or not a known format (JPEG, PNG, WebP, AVIF, GIF, TIFF) the image will be served as-is
- When src is SVG format, it will be blocked unless `unoptimized` or `dangerouslyAllowSVG` is enabled
### width
......@@ -493,9 +497,9 @@ module.exports = {
### Acceptable Formats
The default [Image Optimization API](#loader-configuration) will automatically detect the browser's supported image formats via the request's `Accept` header.
The default [Image Optimization API](#loader-configuration) will automatically detect the browser's supported image formats via the request's `Accept` header in order to determine the best output format.
If the `Accept` head matches more than one of the configured formats, the first match in the array is used. Therefore, the array order matters. If there is no match (or the source image is [animated](#animated-images)), the Image Optimization API will fallback to the original image's format.
If the `Accept` header matches more than one of the configured formats, the first match in the array is used. Therefore, the array order matters. If there is no match (or the source image is [animated](#animated-images)), the Image Optimization API will fallback to the original image's format.
If no configuration is provided, the default below is used.
......@@ -507,7 +511,7 @@ module.exports = {
}
```
You can enable AVIF support with the following configuration.
You can enable AVIF support and still fallback to WebP with the following configuration.
```js filename="next.config.js"
module.exports = {
......@@ -517,7 +521,7 @@ module.exports = {
}
```
> **Good to know**: AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
> **Good to know**: AVIF generally takes 50% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
## Caching Behavior
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment