From d57d9a51737194a34c3e14822e59c361b4578ea8 Mon Sep 17 00:00:00 2001
From: Sam Poder <39828164+sampoder@users.noreply.github.com>
Date: Sat, 14 Aug 2021 11:56:33 +0800
Subject: [PATCH] Add a Styling Section to next/image component docs (#28055)

## Feature

- [x] Documentation added

## Documentation / Examples

- [x] Make sure the linting passes

It seems that people currently struggle to style their image: https://twitter.com/achrlswrth/status/1425695122029744128, this clarifies that you can use className to do this (something I just learnt!). At the moment, this is kind of hidden in "other props" I think this makes it more clear for people

Thanks,

Sam
---
 docs/api-reference/next/image.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md
index eb1e696501e2fe5..05b53dedb83ae34 100644
--- a/docs/api-reference/next/image.md
+++ b/docs/api-reference/next/image.md
@@ -263,6 +263,14 @@ Other properties on the `<Image />` component will be passed to the underlying
 - `ref`. Use [`onLoadingComplete`](#onloadingcomplete) instead.
 - `decoding`. It is always `"async"`.
 
+## Styling
+
+`next/image` wraps the `img` element with other `div` elements to maintain the aspect ratio of the image and prevent [Cumulative Layout Shift](https://vercel.com/blog/core-web-vitals#cumulative-layout-shift).
+
+To add styles to the underlying `img` element, pass the `className` prop to the `<Image />` component. Then, use Next.js' [built-in CSS support](/docs/basic-features/built-in-css-support.md) to add rules to that class.
+
+**Note:** If using [`layout="fill"`](/docs/api-reference/next/image.md#layout), ensure the parent element uses `position: relative`.
+
 ## Related
 
 For more information on what to do next, we recommend the following sections: