You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
Copy file name to clipboardExpand all lines: docs/02-app/02-api-reference/01-components/image.mdx
+9-5Lines changed: 9 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -89,7 +89,11 @@ Must be one of the following:
89
89
- A [statically imported](/docs/app/building-your-application/optimizing/images#local-images) image file
90
90
- A path string. This can be either an absolute external URL, or an internal path depending on the [loader](#loader) prop.
91
91
92
-
When using an external URL, you must add it to [remotePatterns](#remotepatterns) in `next.config.js`.
92
+
When using the default [loader](#loader), also consider the following for source images:
93
+
94
+
- When src is an external URL, you must also configure [remotePatterns](#remotepatterns)
95
+
- When src is [animated](#animated-images) or not a known format (JPEG, PNG, WebP, AVIF, GIF, TIFF) the image will be served as-is
96
+
- When src is SVG format, it will be blocked unless [`unoptimized`](#unoptimized)` or [`dangerouslyAllowSVG`](#dangerouslyallowsvg) is enabled
93
97
94
98
### `width`
95
99
@@ -678,9 +682,9 @@ module.exports = {
678
682
679
683
### `formats`
680
684
681
-
The default [Image Optimization API](#loader) will automatically detect the browser's supported image formats via the request's `Accept` header.
685
+
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.
682
686
683
-
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.
687
+
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.
684
688
685
689
If no configuration is provided, the default below is used.
686
690
@@ -692,7 +696,7 @@ module.exports = {
692
696
}
693
697
```
694
698
695
-
You can enable AVIF support with the following configuration.
699
+
You can enable AVIF support and still fallback to WebP with the following configuration.
696
700
697
701
```js filename="next.config.js"
698
702
module.exports= {
@@ -704,7 +708,7 @@ module.exports = {
704
708
705
709
> **Good to know**:
706
710
>
707
-
> - 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.
711
+
> - 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.
708
712
> - If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the `Accept` header.
Copy file name to clipboardExpand all lines: docs/03-pages/02-api-reference/01-components/image-legacy.mdx
+9-5Lines changed: 9 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -41,7 +41,11 @@ Must be one of the following:
41
41
- A [statically imported](/docs/pages/building-your-application/optimizing/images#local-images) image file
42
42
- 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).
43
43
44
-
When using an external URL, you must add it to [remotePatterns](#remote-patterns) in `next.config.js`.
44
+
When using the default [loader](#loader), also consider the following for source images:
45
+
46
+
- When src is an external URL, you must also configure [remotePatterns](#remote-patterns)
47
+
- When src is [animated](#animated-images) or not a known format (JPEG, PNG, WebP, AVIF, GIF, TIFF) the image will be served as-is
48
+
- When src is SVG format, it will be blocked unless `unoptimized` or `dangerouslyAllowSVG` is enabled
45
49
46
50
### width
47
51
@@ -493,9 +497,9 @@ module.exports = {
493
497
494
498
### Acceptable Formats
495
499
496
-
The default [Image Optimization API](#loader-configuration) will automatically detect the browser's supported image formats via the request's `Accept` header.
500
+
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.
497
501
498
-
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.
502
+
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.
499
503
500
504
If no configuration is provided, the default below is used.
501
505
@@ -507,7 +511,7 @@ module.exports = {
507
511
}
508
512
```
509
513
510
-
You can enable AVIF support with the following configuration.
514
+
You can enable AVIF support and still fallback to WebP with the following configuration.
511
515
512
516
```js filename="next.config.js"
513
517
module.exports= {
@@ -517,7 +521,7 @@ module.exports = {
517
521
}
518
522
```
519
523
520
-
> **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.
524
+
> **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.
0 commit comments