<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" />

File Location

Images should be stored in the static directory.

For example, the nuxt-icon.png referred to in the previous example should be placed in static folder under the path /static/nuxt-icon.png.

In other words, image stored in the assets directory are not compatible with Nuxt Image because those images are managed by webpack.

For more information, you can learn more about the static directory here.

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

<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="cover" src="/nuxt-icon.png" />
</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 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' }"
/>