Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add next/image docs section for animated images #35123

Merged
merged 4 commits into from Mar 8, 2022
Merged

Add next/image docs section for animated images #35123

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b56ef33
Add `next/image` docs for animated images
styfle Mar 7, 2022
438569d
Mention animated fallback
styfle Mar 7, 2022
f27eacf
Apply suggestion from leerob
styfle Mar 7, 2022
80d88ff
Merge branch 'canary' into next-image-docs-animated
kodiakhq[bot] Mar 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
10 changes: 8 additions & 2 deletions docs/api-reference/next/image.md
View file
Open in desktop
Expand Up @@ -374,7 +374,7 @@ module.exports = {

The default [Image Optimization API](#loader-configuration) will automatically detect the browser's supported image formats via the request's `Accept` header.

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, the Image Optimization API will fallback to the original image's 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 no configuration is provided, the default below is used.

Expand Down Expand Up @@ -408,7 +408,7 @@ The expiration (or rather Max Age) is defined by either the [`minimumCacheTTL`](

- You can configure [`minimumCacheTTL`](#minimum-cache-ttl) to increase the cache duration when the upstream image does not include `Cache-Control` header or the value is very low.
- You can configure [`deviceSizes`](#device-sizes) and [`imageSizes`](#device-sizes) to reduce the total number of possible generated images.
- You can configure [formats](/docs/basic-features/image-optimization.md#acceptable-formats) to disable multiple formats in favor of a single image format.
- You can configure [formats](#acceptable-formats) to disable multiple formats in favor of a single image format.

### Minimum Cache TTL

Expand Down Expand Up @@ -455,6 +455,12 @@ module.exports = {
}
```

### Animated Images

The default [loader](#loader) will automatically bypass Image Optimization for animated images and serve it as-is, since converting all the frames of an animated image on-demand is too slow.
styfle marked this conversation as resolved.
Show resolved Hide resolved

Auto-detection for animated files is best-effort and supports GIF, APNG, and WebP. If you want to explicitly bypass Image Optimization for a given animated image, use the [unoptimized](#unoptimized) prop.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does best effort mean here? Does it look at the file extension? How would it fail?

Copy link
Member Author

@styfle styfle Mar 7, 2022 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The buffer is analyzed using is-animated package which returns true/false. If it returns true, then we bypass. If it returns false, then we optimize the image.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is interesting, i didnt know that we dont optimize animated images. So a site with lots of GIFs wont benefit from our optimizations

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In most cases, animated images are not source images. Instead, they are typically exported from some other source such as a video. Most tools that export to animated gif offer a compression option so theres very few cases where a user would even want to optimize an animated image anyway (so far no one has requested it).


## Related

For an overview of the Image component features and usage guidelines, see:
Expand Down