Unverified Commit 350d4cb8 authored by Steven's avatar Steven Committed by GitHub

Update `next/future/image` docs to mention the difference with `next/image` (#38108)

This PR update the `next/future/image` docs to mention the difference with `next/image`
parent dd1492d3
...@@ -13,7 +13,31 @@ description: Try the latest Image Optimization with the experimental `next/futur ...@@ -13,7 +13,31 @@ description: Try the latest Image Optimization with the experimental `next/futur
</details> </details>
> **Note: This is API documentation for the Image Component and Image Optimization. For a feature overview and usage information for images in Next.js, please see [Images](/docs/basic-features/image-optimization.md).** The `next/future/image` component is an experiment to improve both the performance and developer experience of `next/image` by using the native `<img>` element with better default behavior.
This new component is considered experimental and therefore not covered by semver, and may cause unexpected or broken application behavior. Furthermore, it may not work in every browser due to native features that are not polyfilled.
In order to try it out today, you must add the following to your `next.config.js` file, as shown below:
```js
module.exports = {
experimental: {
images: {
allowFutureImage: true,
},
},
}
```
Compared to `next/image`, the new `next/future/image` component has the following changes:
- Renders a single `<img>` without `<div>` or `<span>` wrappers
- Adds support for canonical `style` prop
- Removes `layout`, `objectFit`, and `objectPosition` props in favor of `style` or `className`
- Removes `IntersectionObserver` implementation in favor of [native lazy loading](https://caniuse.com/loading-lazy-attr)
- Removes `loader` config in favor of [`loader`](#loader) prop
- Note: there is no `fill` mode so `width` & `height` props are required
- Note: the [`onError`](#onerror) prop might behave differently
## Required Props ## Required Props
...@@ -247,9 +271,7 @@ module.exports = { ...@@ -247,9 +271,7 @@ module.exports = {
Other properties on the `<Image />` component will be passed to the underlying Other properties on the `<Image />` component will be passed to the underlying
`img` element with the exception of the following: `img` element with the exception of the following:
- `srcSet`. Use - `srcSet`. Use [Device Sizes](#device-sizes) instead.
[Device Sizes](#device-sizes)
instead.
- `ref`. Use [`onLoadingComplete`](#onloadingcomplete) instead. - `ref`. Use [`onLoadingComplete`](#onloadingcomplete) instead.
- `decoding`. It is always `"async"`. - `decoding`. It is always `"async"`.
......
...@@ -28,6 +28,12 @@ To add an image to your application, import the [`next/image`](/docs/api-referen ...@@ -28,6 +28,12 @@ To add an image to your application, import the [`next/image`](/docs/api-referen
import Image from 'next/image' import Image from 'next/image'
``` ```
Alternatively, you can import [`next/future/image`](/docs/api-reference/next/future/image.md) if you need a component much closer to the native `<img>` element:
```jsx
import Image from 'next/future/image'
```
Now, you can define the `src` for your image (either local or remote). Now, you can define the `src` for your image (either local or remote).
### Local Images ### Local Images
...@@ -167,6 +173,8 @@ If none of the suggested methods works for sizing your images, the `next/image` ...@@ -167,6 +173,8 @@ If none of the suggested methods works for sizing your images, the `next/image`
## Styling ## Styling
> Note: Many of the styling issues listed below can be solved with [`next/future/image`](/docs/api-reference/next/future/image.md)
Styling the Image component is not that different from styling a normal `<img>` element, but there are a few guidelines to keep in mind: Styling the Image component is not that different from styling a normal `<img>` element, but there are a few guidelines to keep in mind:
**Pick the correct layout mode** **Pick the correct layout mode**
......
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