---
title: "<NuxtImg>"
description: "Discover how to use and configure the Nuxt Image component."
canonical_url: "https://nuxt.com/modules/image/usage/nuxt-img"
---
# \<NuxtImg>

> Discover how to use and configure the Nuxt Image component.

`<NuxtImg>` is a drop-in replacement for the native `<img>` tag.

- Uses built-in provider to optimize local and remote images
- Converts `src` to provider optimized URLs
- Automatically resizes images based on `width` and `height`
- Generates responsive sizes when providing `sizes` option
- Supports native lazy loading as well as other `<img>` attributes

## Usage

`<NuxtImg>` outputs a native `img` tag directly (without any wrapper around it). Use it like you would use the `<img>` tag:

```vue
<NuxtImg src="/nuxt-icon.png" />
```

Will result in:

```html
<img src="/nuxt-icon.png">
```

::note
With [default provider](https://nuxt.com/modules/image/providers), you should put `/nuxt-icon.png` inside the `public/` directory to make the above example work.
::

## Props

### `custom`

The `custom` prop determines whether `<NuxtImg>` should render as a simple `<img>` element or only serve as a provider for custom rendering. When set to `true`, it disables the default rendering behavior, allowing full control over how the image is displayed. This is useful for implementing custom functionalities, such as placeholders.

When using the `custom` prop, `<NuxtImg>` passes necessary data and attributes to its default slot. You can access the following values via the `v-slot` directive:

- `imgAttrs`: Attributes for the `<img>` element (e.g., `alt`, `width`, `height`, `srcset`, `sizes`).
- `src`: The computed image source URL.
- `isLoaded`: A boolean indicating whether the image has been loaded.

#### Example Usage

```vue
<NuxtImg
  src="/images/nuxt.png"
  alt="image"
  width="400"
  height="400"
  :custom="true"
  v-slot="{ src, isLoaded, imgAttrs }"
>
  <!-- Show the actual image when loaded -->
  <img
    v-if="isLoaded"
    v-bind="imgAttrs"
    :src="src"
  >

  <!-- Show a placeholder while loading -->
  <img
    v-else
    src="https://placehold.co/400x400"
    alt="placeholder"
  >
</NuxtImg>
```

This approach ensures flexibility for custom rendering scenarios, while `<NuxtImg>` continues to handle image optimization and data provisioning behind the scenes.

### `src`

Path to image file

`src` should be in the form of an absolute path for static images in `public/` directory.
Otherwise path that is expected by provider that starts with `/` or a URL.

```vue
<NuxtImg src="/nuxt.png" />
```

For image optimization when using external URLs in `src`, we need to whitelist them using [`domains`](https://nuxt.com/modules/image/configuration#domains) option.

### `width` / `height`

Specify width/height of the image.

- Use desired width/height for static sized images like icons or avatars
- Use original image width/height for responsive images (when using [`sizes`](#sizes))

### `alt`

Although Nuxt Image does not apply any special handling, it's worth mentioning the `alt` attribute. It is a [native](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt) global attribute that specifies an alternate text for an image, if the image cannot be displayed.

It *should always* be provided.

- The text should describe the image if the image contains information
- The text should explain where the link goes if the image is inside an `<a>` element
- Use `alt=""` if the image is only for decoration

```vue
<NuxtImg
  src="/nuxt.png"
  alt="My image file description"
/>
```

### `sizes`

Specify responsive sizes.

This is a space-separated list of screen size/width pairs. You can [see a list of the defined screen sizes here](https://nuxt.com/modules/image/configuration#screens).

By default Nuxt generates *responsive-first* sizing.

- If you omit a screen size prefix (like `sm:`) then this size is the 'default' size of the image. Otherwise, Nuxt will pick the smallest size as the default size of the image.
- This default size is used up until the next specified screen width, and so on. Each specified size pair applies *up* - so `md:400px` means that the image will be sized `400px` on `md` screens and up.

**Example:**

```vue
<NuxtImg
  src="/logos/nuxt.png"
  sizes="100vw sm:50vw md:400px"
/>
```

### `densities`

The `densities` prop serves high-resolution images for Retina/HiDPI screens.

Nuxt Image generates multiple versions at different pixel densities and creates the appropriate `srcset`.

When you specify densities, Nuxt Image multiplies your base dimensions by each density value to generate the corresponding image sizes.

**Example:**

```vue
<!-- Small icon, sharp on all screen densities -->
<NuxtImg 
  src="/nuxt.png"
  height="50"
  densities="x1 x2"
/>
```

Will result in:

```html
<!-- Rendered HTML -->
<img
  src="/_ipx/w_50/nuxt.png"
  srcset="/_ipx/w_50/nuxt.png 1x,
          /_ipx/w_100/nuxt.png 2x"
/>
```

### `placeholder`

Display a placeholder image before the actual image is fully loaded.

You can also use the [custom prop](https://nuxt.com/modules/image/usage/nuxt-img#custom) to make any placeholder you want.

The placeholder prop can be either a string, a boolean, a number, or an array. The usage is shown below for each case.

```vue
<!-- Automatically generate a placeholder based on the original image -->
<NuxtImg src="/nuxt.png" placeholder />

<!-- Set a width, height for the automatically generated placeholder  -->
<NuxtImg src="/nuxt.png" :placeholder="[50, 25]" />

<!-- Set a width, height, quality & blur for the automatically generated placeholder  -->
<NuxtImg src="/nuxt.png" :placeholder="[50, 25, 75, 5]" />

<!-- Set the width & height of the automatically generated placeholder, image will be a square -->
<NuxtImg src="/nuxt.png" :placeholder="15" />

<!-- Provide your own image -->
<NuxtImg src="/nuxt.png" placeholder="./placeholder.png" />
```

You can also leverage [`useImage()`](https://nuxt.com/modules/image/usage/use-image) to generate a placeholder image based on the original image, can be useful if the source is an SVG or you want better control on the modifiers:

```vue
<template>
  <NuxtImg
    src="/nuxt.svg"
    :placeholder="img(`/nuxt.svg`, { height: 10, format: 'png', blur: 2, quality: 50 })"
  />
</template>

<script setup lang="ts">
const img = useImage()
</script>
```

### `placeholder-class`

When using a placeholder, you can use `placeholder-class` to apply a class to the original underlying `<img>` element (while the placeholder is being rendered).

```vue
<!-- Apply a static class to the original image -->
<NuxtImg
  src="/nuxt.png"
  placeholder
  placeholder-class="custom"
/>

<!-- Apply a dynamic class to the original image -->
<NuxtImg
  src="/nuxt.png"
  placeholder
  :placeholder-class="custom"
/>
```

::tip
If you need to apply some CSS to only the *loaded* image you can do so with something like:

```css
img:not(.my-placeholder-class) {
  /* styles here */
}
```
::

### `provider`

Use other provider instead of default [provider option](https://nuxt.com/modules/image/configuration#provider) specified in `nuxt.config`

**Example:**

::code-group
```vue [index.vue]
<template>
  <NuxtImg
    provider="cloudinary"
    src="/remote/nuxt-org/blog/going-full-static/main.png"
    width="300"
    height="169"
  />
</template>
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  image: {
    cloudinary: {
      baseURL: 'https://res.cloudinary.com/nuxt/image/upload'
    }
  }
})
```
::

### `preset`

Presets are predefined sets of image modifiers that can be used create unified form of images in your projects.

::note
We can define presets using [presets options](https://nuxt.com/modules/image/configuration#presets) in `nuxt.config`
::

::code-group
```vue [index.vue]
<template>
  <NuxtImg preset="cover" src="/nuxt-icon.png" />
</template>
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  image: {
    presets: {
      cover: {
        modifiers: {
          fit: 'cover',
          format: 'jpg',
          width: 300,
          height: 300
        }
      }
    }
  }
})
```
::

### `format`

In case you want to serve images in a specific format, use this prop.

```vue
<NuxtImg
  format="webp"
  src="/nuxt-icon.png"
/>
```

Available formats are `webp`, `avif`, `jpeg`, `jpg`, `png`, `gif` and `svg`. If the format is not specified, it will respect the default image format.

### `quality`

The quality for the generated image(s).

```vue
<NuxtImg
  src="/nuxt.jpg"
  quality="80"
  width="200"
  height="100"
/>
```

### `fit`

The `fit` property specifies the size of the images.
There are five standard values you can use with this property.

- `cover`: (default) Preserving aspect ratio, ensure the image covers both provided dimensions by cropping/clipping to fit
- `contain`: Preserving aspect ratio, contain within both provided dimensions using 'letterboxing' where necessary.
- `fill`: Ignore the aspect ratio of the input and stretch to both provided dimensions.
- `inside`: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
- `outside`: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified.

```vue
<NuxtImg
  fit="cover"
  src="/nuxt-icon.png"
  width="200"
  height="100"
/>
```

::note
Some providers support other values.
::

### `modifiers`

In addition to the standard modifiers, each provider might have its own additional modifiers. Because these modifiers depend on the provider, refer to its documentation to know what can be used.

Using the `modifiers` prop lets you use any of these transformations.

**Example:**

```vue
<NuxtImg
  provider="cloudinary"
  src="/remote/nuxt-org/blog/going-full-static/main.png"
  width="300"
  height="169"
  :modifiers="{ roundCorner: '0:100' }"
/>
```

### `preload`

In case you want to preload the image, use this prop. This will place a corresponding `link` tag in the page's head.

```vue
<NuxtImg src="/nuxt-icon.png" preload />
```

Passing an object to the preload prop lets you define the `fetchPriority` property.
Note that the JavaScript property `fetchPriority` maps to the [`fetchpriority`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/fetchpriority) HTML attribute in the preload link tag.
Accepted values are `auto`, `high`, or `low`.

```vue
<NuxtImg src="/nuxt-icon.png" :preload="{ fetchPriority: 'high' }" />
```

### `loading`

This is a [native](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/loading) attribute that provides a hint
to the browser on how to handle the loading of an image which is outside the viewport.
It is [supported](https://caniuse.com/loading-lazy-attr) by the latest version of all major browsers since March 2022.

Set `loading="lazy"` to defer loading of an image until it appears in the viewport.

```vue
<NuxtImg src="/nuxt-icon.png" loading="lazy" />
```

### `nonce`

This is a [native](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) global attribute that defines a cryptographic nonce (number used once) that can be used by Content Security Policy to determine whether or not a given fetch will be allowed to proceed for a given element.
Providing a nonce allows you to avoid using the CSP `unsafe-inline` directive, which would allowlist *all* inline script or styles.

```vue
<template>
  <NuxtImg
    src="/nuxt-icon.png"
    :nonce="nonce"
  />
</template>

<script setup lang="ts">
// useNonce is not provided by @nuxt/image but might be
// provided by another module, for example nuxt-security
const nonce = useNonce()
</script>
```

## Events

Native events emitted by the `<img>` element contained by `<NuxtImg>` and `<NuxtPicture>` components are re-emitted and can be listened to.

**Example:** Listen to the native `onLoad` event from `<NuxtImg>`

```vue
<NuxtImg
  src="/images/colors.jpg"
  width="500"
  height="500"
  @load="doSomethingOnLoad"
/>
```

---

- [Source](https://github.com/nuxt/image/blob/main/src/runtime/components/NuxtImg.vue)


## Sitemap

See the full [sitemap](https://nuxt.com/sitemap.md) for all pages.