Skip to content

Commit 7b9630f

Browse files
authored
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
1 parent f260aad commit 7b9630f

File tree

2 files changed

+18
-10
lines changed

2 files changed

+18
-10
lines changed

docs/02-app/02-api-reference/01-components/image.mdx

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,11 @@ Must be one of the following:
8989
- A [statically imported](/docs/app/building-your-application/optimizing/images#local-images) image file
9090
- A path string. This can be either an absolute external URL, or an internal path depending on the [loader](#loader) prop.
9191

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
9397

9498
### `width`
9599

@@ -678,9 +682,9 @@ module.exports = {
678682

679683
### `formats`
680684

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.
682686

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.
684688

685689
If no configuration is provided, the default below is used.
686690

@@ -692,7 +696,7 @@ module.exports = {
692696
}
693697
```
694698

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.
696700

697701
```js filename="next.config.js"
698702
module.exports = {
@@ -704,7 +708,7 @@ module.exports = {
704708

705709
> **Good to know**:
706710
>
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.
708712
> - If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the `Accept` header.
709713
710714
## Caching Behavior

docs/03-pages/02-api-reference/01-components/image-legacy.mdx

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,11 @@ Must be one of the following:
4141
- A [statically imported](/docs/pages/building-your-application/optimizing/images#local-images) image file
4242
- 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).
4343

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
4549

4650
### width
4751

@@ -493,9 +497,9 @@ module.exports = {
493497

494498
### Acceptable Formats
495499

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.
497501

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.
499503

500504
If no configuration is provided, the default below is used.
501505

@@ -507,7 +511,7 @@ module.exports = {
507511
}
508512
```
509513

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.
511515

512516
```js filename="next.config.js"
513517
module.exports = {
@@ -517,7 +521,7 @@ module.exports = {
517521
}
518522
```
519523

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.
521525
522526
## Caching Behavior
523527

0 commit comments

Comments
 (0)