From 0777abfd9889c0482876c473c602bf22afd34504 Mon Sep 17 00:00:00 2001
From: a1mer <onlylovesnow14@gmail.com>
Date: Fri, 20 Dec 2024 09:13:56 +0800
Subject: [PATCH] docs: supplement responsive usage

---
 docs/content/2.usage/1.nuxt-img.md | 41 ++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/docs/content/2.usage/1.nuxt-img.md b/docs/content/2.usage/1.nuxt-img.md
index 6b8cfa751..03275525a 100644
--- a/docs/content/2.usage/1.nuxt-img.md
+++ b/docs/content/2.usage/1.nuxt-img.md
@@ -18,6 +18,8 @@ links:
 
 ## Usage
 
+### Basic
+
 `<NuxtImg>` outputs a native `img` tag directly (without any wrapper around it). Use it like you would use the `<img>` tag:
 
 ```html
@@ -34,6 +36,45 @@ Will result in:
 With [default provider](/get-started/providers), you should put `/nuxt-icon.png` inside `public/` directory for Nuxt 3 make the above example work.
 ::
 
+### Responsive
+When you put an image on your site, you usually want both enough image sharpness and best performance(i.e. minimal download size). There are two paths to achieve these purposes:
+
+#### By densities only
+If you're sure the image will always be a certain size, for example 400px, you can use `<NuxtImg>` like this:
+```html
+<NuxtImg src="/nuxt.png" width="400px" />
+```
+Output will be like:
+```html
+<img
+  width="400"
+  srcset="/_ipx/w_400/images/nuxt.png 1x, /_ipx/w_800/images/nuxt.png 2x"
+>
+```
+By default(densities="x1 x2"), on [dpr(devicePixelRatio)=1] devices, `/_ipx/w_400/images/nuxt.png` will be used, on [dpr>=2] devices, `/_ipx/w_800/images/nuxt.png` will be used.  
+
+Note in this case, the `width` property is important, if you provide neither `width` nor `height`, the two generated image urls will be same, which is meanlingless.
+
+#### By media query and densites
+If the image will be different sizes on different window sizes, you may use `<NuxtImg>` like this:
+```html
+<NuxtImg
+  src="/nuxt.png"
+  sizes="300px lg:700px"
+/>
+```
+Output will be like:
+```html
+<img
+  sizes="(max-width: 1024px) 300px, 700px"
+  srcset="/_ipx/w_300/nuxt.png 300w, /_ipx/w_600/nuxt.png 600w, /_ipx/w_700/nuxt.png 700w, /_ipx/w_1400/nuxt.png 1400w"
+>
+```
+On [dpr=1] devices, if `screenWidth <= 1024`, `/_ipx/w_300/nuxt.png,` will be used, otherwise, `/_ipx/w_700/nuxt.png` will be used.  
+On [dpr=2] devices, if `screenWidth <= 1024`, `/_ipx/w_600/nuxt.png` will be used(300 x 2), otherwise, `/_ipx/w_1400/nuxt.png` will be used(700 x 2).
+
+As you can see from this example, the unit `w` in `srcset` doesn't mean exactly `px`, it also takes `dpr` into account.
+
 ## Props
 
 ### `src`