Update Image docs with links to examples (vercel#18770)

This revises the docs to add headings and also links to layout examples.

Fixes vercel#18554

docs/api-reference/next/image.md

@@ -15,6 +15,8 @@ description: Enable Image Optimization with the built-in Image component.
 
 Image Optimization can be enabled via the `Image` component exported by `next/image`.
 
+## Usage
+
 For an example, consider a project with the following files:
 
 - `pages/index.js`
@@ -43,17 +45,99 @@ function Home() {
 export default Home
 ```
 
-`Image` accepts the following props:
+## Required Props
+
+The `Image` component requires the following properties.
+
+### src
+
+The path or URL to the source image. This is required.
+
+When using an external URL, you must add it to [domains](/docs/basic-features/image-optimization.md#domains) in `next.config.js`.
+
+### width
+
+The width of the image, in pixels. Must be an integer without a unit.
+
+Required unless [layout="fill"`](#layout).
+
+### height
+
+The height of the image, in pixels. Must be an integer without a unit.
+
+Required unless [layout="fill"`](#layout).
+
+## Optional Props
+
+The `Image` component optionally accepts the following properties.
+
+### layout
+
+The layout behavior of the image as the viewport changes size. Defaults to `intrinsic`.
+
+When `fixed`, the image dimensions will not change as the viewport changes (no responsiveness) similar to the native `img` element.
+
+When `intrinsic`, the image will scale the dimensions down for smaller viewports but maintain the original dimensions for larger viewports.
+
+When `responsive`, the image will scale the dimensions down for smaller viewports and scale up for larger viewports.
+
+When `fill`, the image will stretch both width and height to the dimensions of the parent element, usually paired with [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit).
+
+Try it out:
+
+- [Demo the `fixed` layout](https://image-component.nextjs.gallery/layout-fixed)
+- [Demo the `intrinsic` layout](https://image-component.nextjs.gallery/layout-intrinsic)
+- [Demo the `responsive` layout](https://image-component.nextjs.gallery/layout-responsive)
+- [Demo the `fill` layout](https://image-component.nextjs.gallery/layout-fill)
+- [Demo background image](https://image-component.nextjs.gallery/background)
+
+### sizes
+
+Defines what proportion of the screen you expect the image to take up. Defaults to undefined.
+
+Recommended, as it helps serve the correct sized image to each device.
+
+[Learn more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes).
+
+### quality
+
+The quality of the optimized image, an integer between 1 and 100 where 100 is the best quality. Defaults to 75.
+
+### priority
+
+When true, the image will be considered high priority and [preload](https://web.dev/preload-responsive-images/).
+
+Should only be used when the image is visible above the fold. Defaults to false.
+
+## Advanced Props
+
+In some cases, you may need more advanced usage. The `Image` component optionally accepts the following advanced properties.
+
+### loading
+
+The loading behavior of the image. Defaults to `lazy`.
+
+When `lazy`, defer loading the image until it reaches a calculated distance from the viewport.
+
+When `eager`, load the image immediately.
+
+[Learn more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading)
+
+### unoptimized
+
+When true, the source image will be served as-is instead of changing quality, size, or format. Defaults to false.
+
+## Other Props
+
+All other properties on the `Image` component will be passed to the underlying `img` element, except for `style`. Use `className` isntead.
+
+## Related
 
-- `src` - The path or URL to the source image. This is required.
-- `width` - The width of the image, in pixels. Must be an integer without a unit. Required unless `layout="fill"`.
-- `height` - The height of the image, in pixels. Must be an integer without a unit. Required unless `layout="fill"`.
-- `layout` - The rendered layout of the image. If `fixed`, the image dimensions will not change as the viewport changes (no responsiveness). If `intrinsic`, the image will scale the dimensions down for smaller viewports but maintain the original dimensions for larger viewports. If `responsive`, the image will scale the dimensions down for smaller viewports and scale up for larger viewports. If `fill`, the image will stretch both width and height to the dimensions of the parent element. Default `intrinsic`.
-- `sizes` - Defines what proportion of the screen you expect the image to take up. Recommended, as it helps serve the correct sized image to each device. [More info](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes).
-- `quality` - The quality of the optimized image, an integer between 1 and 100 where 100 is the best quality. Default 75.
-- `loading` - The loading behavior. When `lazy`, defer loading the image until it reaches a calculated distance from the viewport. When `eager`, load the image immediately. Default `lazy`. [More info](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading)
-- `priority` - When true, the image will be considered high priority and [preload](https://web.dev/preload-responsive-images/). Should only be used when the image is visible above the fold.
-- `unoptimized` - When true, the source image will be served as-is instead of changing quality, size, or format.
-- `unsized` - **Deprecated** When true, the `width` and `height` requirement can by bypassed. Use the `layout` property instead!
+For more information on what to do next, we recommend the following sections:
 
-All other properties on the `<Image>` component will be passed to the underlying `<img>` element.
+<div class="card">
+  <a href="/docs/basic-features/image-optimization.md">
+    <b>Image Optimization</b>
+    <small>See how to configure domains and loaders.</small>
+  </a>
+</div>

docs/basic-features/image-optimization.md

@@ -56,48 +56,6 @@ export default Home
 
 In addition to [using properties](/docs/api-reference/next/image.md) available to the `next/image` component, you can optionally configure Image Optimization for more advanced use cases via `next.config.js`.
 
-If no configuration is provided, the following default configuration will be used.
-
-```js
-module.exports = {
-  images: {
-    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
-    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
-    domains: [],
-    path: '/_next/image',
-    loader: 'default',
-  },
-}
-```
-
-If a specific property is omitted, such as `deviceSizes`, that property will use the default above.
-
-This means you only need to configure the properties you wish to change.
-
-### Device Sizes
-
-You can specify a list of device width breakpoints using the `deviceSizes` property. These widths are used when the [`next/image`](/docs/api-reference/next/image.md) component uses `layout="responsive"` or `layout="fill"` so that the correct image is served for the device visiting your website.
-
-```js
-module.exports = {
-  images: {
-    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
-  },
-}
-```
-
-### Image Sizes
-
-You can specify a list of image widths using the `imageSizes` property. These widths should be different than the widths defined in `deviceSizes` because the arrays will be concatentated. These widths are used when the [`next/image`](/docs/api-reference/next/image.md) component uses `layout="fixed"` or `layout="intrinsic"`.
-
-```js
-module.exports = {
-  images: {
-    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
-  },
-}
-```
-
 ### Domains
 
 To enable Image Optimization for images hosted on an external website, use an absolute url for the Image `src` and specify which
@@ -113,7 +71,7 @@ module.exports = {
 
 ### Loader
 
-If you want to use a cloud image provider to optimize images instead of using the Next.js' built-in image optimization, you can configure the loader and path prefix. This allows you to use relative urls for the Image `src` and automatically generate the correct absolute url for your provider.
+If you want to use a cloud provider to optimize images instead of using the Next.js' built-in Image Optimization, you can configure the loader and path prefix. This allows you to use relative urls for the Image `src` and automatically generate the correct absolute url for your provider.
 
 ```js
 module.exports = {
@@ -130,7 +88,7 @@ The following Image Optimization cloud providers are supported:
 - [Imgix](https://www.imgix.com): `loader: 'imgix'`
 - [Cloudinary](https://cloudinary.com): `loader: 'cloudinary'`
 - [Akamai](https://www.akamai.com): `loader: 'akamai'`
-- Other: Works automatically with `next dev`, `next start`, or a custom server
+- Default: Works automatically with `next dev`, `next start`, or a custom server
 
 ## Caching
 
@@ -144,6 +102,38 @@ If `s-maxage` is found in `Cache-Control`, it is used. If no `s-maxage` is found
 
 You can configure [`deviceSizes`](#device-sizes) and [`imageSizes`](#device-sizes) to reduce the total number of possible generated images.
 
+## Advanced
+
+The following configuration is for advanced use cases and is usually not necessary. If you choose to configure the properties below, you will override any changes to the Next.js defaults in future updates.
+
+### Device Sizes
+
+In some cases, where you know the expected device widths from the users of your website, you can specify a list of device width breakpoints using the `deviceSizes` property. These widths are used when the [`next/image`](/docs/api-reference/next/image.md) component uses `layout="responsive"` or `layout="fill"` so that the correct image is served for the device visiting your website.
+
+If no configuration is provided, the default below is used.
+
+```js
+module.exports = {
+  images: {
+    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+  },
+}
+```
+
+### Image Sizes
+
+You can specify a list of image widths using the `imageSizes` property. These widths should be different (usually smaller) than the widths defined in `deviceSizes` because the arrays will be concatentated. These widths are used when the [`next/image`](/docs/api-reference/next/image.md) component uses `layout="fixed"` or `layout="intrinsic"`.
+
+If no configuration is provided, the default below is used.
+
+```js
+module.exports = {
+  images: {
+    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
+  },
+}
+```
+
 ## Related
 
 For more information on what to do next, we recommend the following sections:

examples/image-component/app.css

@@ -0,0 +1,19 @@
+body {
+  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+  margin: 0;
+  padding: 0;
+  background: black;
+  color: white;
+}
+
+a {
+  cursor: pointer;
+  color: #0076ff;
+  text-decoration: none;
+  transition: all 0.2s ease;
+  border-bottom: 1px solid black;
+}
+
+a:hover {
+  border-bottom: 1px solid #0076ff;
+}

examples/image-component/pages/_app.js

@@ -0,0 +1,5 @@
+import '../app.css'
+
+export default function MyApp({ Component, pageProps }) {
+  return <Component {...pageProps} />
+}

examples/image-component/pages/background.js

@@ -1,46 +1,22 @@
 import Image from 'next/image'
+import { bgWrap, bgText, objectFitCover } from '../styles.module.css'
 
 const Background = () => (
   <div>
-    <div className="container">
+    <div className={bgWrap}>
       <Image
         alt="Mountains"
         src="/mountains.jpg"
         layout="fill"
         quality={100}
-        className="cover"
+        className={objectFitCover}
       />
     </div>
-    <h1>
+    <p className={bgText}>
       Image Component
       <br />
       as a Background
-    </h1>
-    <style jsx global>{`
-      body {
-        margin: 0;
-        padding: 0;
-        background: black;
-        color: white;
-      }
-      .container {
-        position: fixed;
-        height: 100vh;
-        width: 100vw;
-        overflow: hidden;
-        z-index: -1;
-      }
-      .cover {
-        object-fit: cover;
-      }
-      h1 {
-        margin: 0;
-        font-size: 2rem;
-        line-height: 3rem;
-        text-align: center;
-        padding-top: 40vh;
-      }
-    `}</style>
+    </p>
   </div>
 )
 

examples/image-component/pages/index.js

@@ -11,7 +11,7 @@ const Index = () => (
       <p>
         The images below use the{' '}
         <a href="https://nextjs.org/docs/api-reference/next/image">
-          &lt;Image&gt;
+          next/image
         </a>{' '}
         component to ensure optimal format and size for this browser.
       </p>
@@ -37,34 +37,40 @@ const Index = () => (
       </p>
       <p>
         External domains must be configured in <Code>next.config.js</Code> using
-        the <Code>domains</Code>.
+        the <Code>domains</Code> property.
       </p>
       <Image
         alt="Next.js logo"
-        src="https://assets.vercel.com/image/upload/v1538361091/repositories/next-js/next-js.png"
+        src="https://assets.vercel.com/image/upload/v1538361091/repositories/next-js/next-js-bg.png"
         width={1200}
         height={400}
       />
       <hr className={styles.hr} />
       <h2>Layouts</h2>
       <p>
-        The following demonstrate the <Code>layout</Code> property options
+        The following pages demonstrate possible <Code>layout</Code> property
+        values.
+      </p>
+      <p>
+        Click on one to try it out with your current device and be sure to
+        change the window size or rotate your device to see how the image
+        reacts.
       </p>
       <ul>
         <li>
-          <Link href="/layout-intrinsic">intrinsic</Link>
+          <Link href="/layout-intrinsic">layout="intrinsic"</Link>
         </li>
         <li>
-          <Link href="/layout-responsive">responsive</Link>
+          <Link href="/layout-responsive">layout="responsive"</Link>
         </li>
         <li>
-          <Link href="/layout-fixed">fixed</Link>
+          <Link href="/layout-fixed">layout="fixed"</Link>
         </li>
         <li>
-          <Link href="/layout-fill">fill</Link>
+          <Link href="/layout-fill">layout="fill"</Link>
         </li>
         <li>
-          <Link href="/background">background</Link>
+          <Link href="/background">background demo</Link>
         </li>
       </ul>
       <hr className={styles.hr} />