Usage of <nuxt-img> component

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
  • Support loading="lazy" for wider range of browsers including Safari using IntersectionObserver
  • Generates responsive sizes when providing sizes option

Use it like you would use the <img> tag:

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

Will result in:

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

Props

src

Path to image file

src should be in the form of an absolute path for static images in static/ 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 reiszes.

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:

<template>
  <nuxt-img
    provider="cloudinary"
    src="/remote/nuxt-org/blog/going-full-static/main.png"
    width="300"
    height="169"
  />
</template>
nuxt.config.js
export default {
  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 option in nuxt.config
<template>
  <nuxt-img preset="jpg-cover" src="/nuxt-icon.png" width="50" height="50" />
</template>
export default {
  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, 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 standard modifiers, every provider can have their own modifiers.

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' }"
/>
Edit this page on GitHub Updated at Mon, Feb 15, 2021