Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: supplement responsive usage #1642

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: supplement responsive usage #1642

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0777abf
docs: supplement responsive usage
a1mersnow Dec 20, 2024
8c78a83
Merge branch 'main' into feat/docs
a1mersnow Jan 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions docs/content/2.usage/1.nuxt-img.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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`
Expand Down