Usage

<NuxtImg>

Source
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:

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

Will result in:

<img src="/nuxt-icon.png" />
With default provider, you should put /nuxt-icon.png inside public/ directory for Nuxt 3 make the above example work.

Props

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.

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

For image optimization when using external urls in src, we need to whitelist them using 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

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).

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:

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

densities

To generate special versions of images for screens with increased pixel density.

Example:

<NuxtImg
  src="/logos/nuxt.png"
  height="50"
  densities="x1 x2"
/>
<!--
<img
  src="/_ipx/w_50/logos/nuxt.png" 
  srcset="/_ipx/w_100/logos/nuxt.png x2"
/>
-->

placeholder

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

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

<!-- 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() 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:

<script setup>
const img = useImage()
</script>

<template>
  <NuxtImg :placeholder="img(`/nuxt.svg`, { h: 10, f: 'png', blur: 2, q: 50 })" src="/nuxt.svg`" />
</template>

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).

<!-- 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" />
If you need to apply some CSS to only the loaded image you can do so with something like:
img:not(.my-placeholder-class) {
  /* styles here */
}

provider

Use other provider instead of default provider option specified in nuxt.config

Example:

<template>
  <NuxtImg
    provider="cloudinary"
    src="/remote/nuxt-org/blog/going-full-static/main.png"
    width="300"
    height="169"
  />
</template>

preset

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

We can define presets using presets options in nuxt.config
<template>
  <NuxtImg preset="cover" src="/nuxt-icon.png" />
</template>

format

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

<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).

<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.
<NuxtImg fit="cover" src="/nuxt-icon.png" width="200" height="100" />
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:

<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.

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

loading

This is a native 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 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.

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

nonce

This is a native 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.

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

<script lang="ts" setup>
// 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>

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

Contributing

We can never thank you enough for your contributions.

<NuxtPicture>

Discover how to use and configure the Nuxt Picture component.