<nuxt-img>

Discover how to use and configure the nuxt-img component.

<nuxt-img> 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

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

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

<nuxt-img 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 a space-separated list of screen size/width pairs. You can see a list of the defined screen sizes here).

Example:

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

provider

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

Example:

index.vue
<template>
  <nuxt-img
    provider="cloudinary"
    src="/remote/nuxt-org/blog/going-full-static/main.png"
    width="300"
    height="169"
  />
</template>
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.

We can define presets using presets options in nuxt.config
index.vue
<template>
  <nuxt-img preset="cover" src="/nuxt-icon.png" />
</template>
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.

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

<nuxt-img 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.
<nuxt-img 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:

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

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

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

Events

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

Example: Listen to the native onLoad event from <nuxt-img>

<nuxt-img
  src="/images/colors.jpg"
  width="500"
  height="500"
  @load="doSomethingOnLoad"
/>
Table of Contents