Update example for Image Component (vercel#18762)

docs/api-reference/next/image.md

@@ -52,8 +52,8 @@ export default Home
 - `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/).
-- `unoptimized` - When true, the source image will be served as-is instead of resizing and changing quality.
+- `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!
 
 All other properties on the `<Image>` component will be passed to the underlying `<img>` element.

docs/basic-features/image-optimization.md

@@ -23,6 +23,8 @@ Instead of optimizing images at build time, Next.js optimizes images on-demand,
 
 Images are lazy loaded by default. That means your page speed isn't penalized for images outside the viewport. Images load as they are scrolled into viewport.
 
+Images are always rendered in such a way as to avoid prevent [Cumulative Layout Shift](https://web.dev/cls/), a [Core Web Vital](https://web.dev/vitals/) that Google is going to [use in search ranking](https://webmasters.googleblog.com/2020/05/evaluating-page-experience.html).
+
 ## Image Component
 
 To add an image to your application, import the [`next/image`](/docs/api-reference/next/image.md) component:
@@ -48,14 +50,11 @@ function Home() {
 export default Home
 ```
 
-- `width` and `height` are required to prevent [Cumulative Layout Shift](https://web.dev/cls/), a [Core Web Vital](https://web.dev/vitals/) that Google is going to [use in their search ranking](https://webmasters.googleblog.com/2020/05/evaluating-page-experience.html)
-- `width` and `height` are automatically responsive, unlike the HTML `<img>` element
-- `quality` can be configured per image, default 75
-- See [`next/image`](/docs/api-reference/next/image.md) for list of available props.
+[View all properties](/docs/api-reference/next/image.md) available to the `next/image` component.
 
 ## Configuration
 
-You can optionally configure Image Optimization by using the `images` property in `next.config.js`.
+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.
 
@@ -127,11 +126,11 @@ module.exports = {
 
 The following Image Optimization cloud providers are supported:
 
-- When using `next start` or a custom server image optimization works automatically.
-- [Vercel](https://vercel.com): Works automatically when you deploy on Vercel, no configuration necessary.
+- [Vercel](https://vercel.com): Works automatically when you deploy on Vercel, no configuration necessary. [Learn more](https://vercel.com/docs/next.js/image-optimization)
 - [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
 
 ## Caching
 

examples/image-component/pages/background.js

@@ -0,0 +1,47 @@
+import Image from 'next/image'
+
+const Background = () => (
+  <div>
+    <div className="container">
+      <Image
+        alt="Mountains"
+        src="/mountains.jpg"
+        layout="fill"
+        quality={100}
+        className="cover"
+      />
+    </div>
+    <h1>
+      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>
+  </div>
+)
+
+export default Background

examples/image-component/pages/index.js

@@ -1,5 +1,6 @@
 import styles from '../styles.module.css'
 import Image from 'next/image'
+import Link from 'next/link'
 
 const Code = (p) => <code className={styles.inlineCode} {...p} />
 
@@ -45,6 +46,28 @@ const Index = () => (
         height={400}
       />
       <hr className={styles.hr} />
+      <h2>Layouts</h2>
+      <p>
+        The following demonstrate the <Code>layout</Code> property options
+      </p>
+      <ul>
+        <li>
+          <Link href="/layout-intrinsic">intrinsic</Link>
+        </li>
+        <li>
+          <Link href="/layout-responsive">responsive</Link>
+        </li>
+        <li>
+          <Link href="/layout-fixed">fixed</Link>
+        </li>
+        <li>
+          <Link href="/layout-fill">fill</Link>
+        </li>
+        <li>
+          <Link href="/background">background</Link>
+        </li>
+      </ul>
+      <hr className={styles.hr} />
       Checkout the documentation for{' '}
       <a href="https://nextjs.org/docs/basic-features/image-optimization">
         Image Optimization

examples/image-component/pages/layout-fill.js

@@ -0,0 +1,51 @@
+import Image from 'next/image'
+
+const Fill = () => (
+  <div>
+    <h1>Image Component With Layout Fill</h1>
+    <div style={{ position: 'relative', width: '300px', height: '500px' }}>
+      <Image
+        alt="Mountains"
+        src="/mountains.jpg"
+        layout="fill"
+        className="cover"
+      />
+    </div>
+    <div style={{ position: 'relative', width: '300px', height: '500px' }}>
+      <Image
+        alt="Mountains"
+        src="/mountains.jpg"
+        layout="fill"
+        className="contain"
+      />
+    </div>
+    <div style={{ position: 'relative', width: '300px', height: '500px' }}>
+      <Image
+        alt="Mountains"
+        src="/mountains.jpg"
+        layout="fill"
+        className="none"
+        quality={100}
+      />
+    </div>
+    <style jsx global>{`
+      body {
+        margin: 0;
+        padding: 0;
+        background: black;
+        color: white;
+      }
+      .contain {
+        object-fit: contain;
+      }
+      .cover {
+        object-fit: cover;
+      }
+      .none {
+        object-fit: none;
+      }
+    `}</style>
+  </div>
+)
+
+export default Fill

examples/image-component/pages/layout-fixed.js

@@ -0,0 +1,24 @@
+import Image from 'next/image'
+
+const Fixed = () => (
+  <div>
+    <h1>Image Component With Layout Fixed</h1>
+    <Image
+      alt="Mountains"
+      src="/mountains.jpg"
+      layout="fixed"
+      width={700}
+      height={475}
+    />
+    <style jsx global>{`
+      body {
+        margin: 0;
+        padding: 0;
+        background: black;
+        color: white;
+      }
+    `}</style>
+  </div>
+)
+
+export default Fixed

examples/image-component/pages/layout-intrinsic.js

@@ -0,0 +1,24 @@
+import Image from 'next/image'
+
+const Intrinsic = () => (
+  <div>
+    <h1>Image Component With Layout Intrinsic</h1>
+    <Image
+      alt="Mountains"
+      src="/mountains.jpg"
+      layout="intrinsic"
+      width={700}
+      height={475}
+    />
+    <style jsx global>{`
+      body {
+        margin: 0;
+        padding: 0;
+        background: black;
+        color: white;
+      }
+    `}</style>
+  </div>
+)
+
+export default Intrinsic

examples/image-component/pages/layout-responsive.js

@@ -0,0 +1,24 @@
+import Image from 'next/image'
+
+const Responsive = () => (
+  <div>
+    <h1>Image Component With Layout Responsive</h1>
+    <Image
+      alt="Mountains"
+      src="/mountains.jpg"
+      layout="responsive"
+      width={700}
+      height={475}
+    />
+    <style jsx global>{`
+      body {
+        margin: 0;
+        padding: 0;
+        background: black;
+        color: white;
+      }
+    `}</style>
+  </div>
+)
+
+export default Responsive