Image Optimization

Learn how to optimize images in your Nuxt application with Nuxt Image.

Nuxt has a core module (@nuxt/image) to resize, transform and serve optimized images in your application:

  • Drop-in replacement: Use <NuxtImg> and <NuxtPicture> where you would write <img> and <picture>.
  • Built-in resizer: Optimize local and remote images with IPX, the default provider, with no configuration.
  • 40+ providers supported: Use the image service of your CDN or CMS instead, or write your own provider, with no vendor lock-in.
  • Responsive ready: Serve resized images for each screen size and device pixel density.
  • Modern formats: Convert images to WebP or AVIF for the browsers that support them.
  • Faster page loads: Load images only when they enter the viewport with native lazy loading, and show placeholders while they load.
  • Visual stability: Reserve space for images with width and height to prevent layout shift.

Installation

Add the Nuxt Image module to your project:

Terminal
npx nuxt add image

This command installs @nuxt/image and adds it to the modules of your nuxt.config.

When you use <NuxtImg> or <NuxtPicture> in development without the module, Nuxt detects it and asks to install @nuxt/image for you.

Usage

Use <NuxtImg> instead of <img>, and <NuxtPicture> instead of <picture>. You don't need to import them:

<template>
  <NuxtImg
    src="/nuxt.png"
    alt="Nuxt logo"
    width="300"
    height="80"
  />
</template>

The src property can be a local or remote image.

Local Images

Store your images in the public/ directory and reference them from the root URL (/). For example, public/profile.png is available as /profile.png:

app/pages/index.vue
<template>
  <NuxtImg
    src="/profile.png"
    alt="Picture of the author"
    width="500"
    height="500"
  />
</template>

Nuxt Image resizes the image to the given width and height. The browser also uses these values to reserve space for the image before it loads, which prevents layout shift. Nuxt Image doesn't read the intrinsic dimensions of your files, so always set width and height for images that aren't sized by CSS.

By default, Nuxt Image uses IPX, a self-hosted optimizer that runs on your Nuxt server. When you prerender your site with nuxt generate, Nuxt Image optimizes the images at build time instead.

Prerendering only generates the image sizes that are in the server-rendered HTML. An image that only renders in the browser, such as in a modal or a client-only component, has no generated file, so its URL returns a 404 error. List these images in nitro.prerender.routes, or use an image provider. See static images for more details.

IPX doesn't run in worker runtimes. When you deploy to one, such as Cloudflare Workers, Nuxt Image serves your original images without optimization. Configure an image provider, such as cloudflare, to optimize them.
Nuxt Image doesn't process images in the app/assets/ directory, because your build tool manages them. To keep source images out of public/, set the image.dir option.

Responsive Images

Use the sizes prop to generate several image widths and let the browser pick the right one for the screen. Each value applies from a screen size and up. The screen sizes match the Tailwind CSS breakpoints by default:

app/pages/index.vue
<template>
  <NuxtImg
    src="/hero.jpg"
    alt="Mountains at sunrise"
    width="1600"
    height="900"
    sizes="100vw md:50vw xl:800px"
  />
</template>

In this example, the image fills the screen width on small screens, half of it from the md breakpoint, and is 800 pixels wide from the xl breakpoint. Nuxt Image generates a srcset with one image for each size, at both 1x and 2x pixel density. The sizes prop doesn't set the displayed width of the image, so use CSS to give the image these widths.

Images without sizes, such as icons or avatars, get a 1x and a 2x version by default, so they stay sharp on high-density screens. To change the pixel densities, use the densities prop for a single image, or the image.densities option for every image.

Image Formats

Use the format prop to convert an image to a modern format:

<template>
  <NuxtImg
    src="/hero.jpg"
    alt="Mountains at sunrise"
    format="webp"
  />
</template>

To serve the best format that each browser supports, use <NuxtPicture>. It renders a <picture> element with one source for each format, and a fallback in a legacy format such as JPEG or PNG:

<template>
  <NuxtPicture
    src="/hero.jpg"
    alt="Mountains at sunrise"
    format="avif,webp"
  />
</template>

Loading Priority

Images below the fold can wait until the user scrolls to them. Set loading="lazy" to load an image only when it enters the viewport:

<template>
  <NuxtImg
    src="/gallery/sunset.jpg"
    alt="Sunset over the sea"
    width="400"
    height="300"
    loading="lazy"
  />
</template>

The image that is the Largest Contentful Paint (LCP) of your page, such as a hero image, must load as early as possible. Use the preload prop to add a <link rel="preload"> tag to the page head with a high fetch priority:

<template>
  <NuxtImg
    src="/hero.jpg"
    alt="Mountains at sunrise"
    width="1600"
    height="900"
    :preload="{ fetchPriority: 'high' }"
  />
</template>

Placeholders

To show a blurred, low-quality version of the image while the full image loads, add the placeholder prop:

<template>
  <NuxtImg
    src="/hero.jpg"
    alt="Mountains at sunrise"
    width="1600"
    height="900"
    placeholder
  />
</template>

<NuxtImg> replaces the placeholder with the full image in the browser, so placeholders require JavaScript. Without it, the page keeps showing the placeholder.

You can also pass your own placeholder image, or set its size, quality, and blur. See the placeholder prop for all options.

Remote Images

To use a remote image, provide its URL in the src property:

app/pages/index.vue
<template>
  <NuxtImg
    src="https://images.unsplash.com/photo-1501785888041-af3ef285b470"
    alt="Lake surrounded by mountains"
    width="500"
    height="500"
  />
</template>

To prevent other websites from using your server to optimize any image on the internet, Nuxt Image only optimizes remote images from domains that you allow. Add them to the image.domains option in your nuxt.config:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/image'],
  image: {
    domains: ['images.unsplash.com'],
  },
})

With the default IPX provider, Nuxt Image renders images from other domains with their original URL, without optimization. Other providers can handle these images differently.

Image Providers

If you already host your images on an image CDN or a headless CMS, Nuxt Image can use its transformation service instead of IPX. Nuxt Image supports more than 40 providers, such as Cloudinary, Imgix, Sanity, and Storyblok. When you deploy to Vercel, Netlify, or AWS Amplify, Nuxt Image detects and uses the platform's image service.

To use a provider, set it as the default provider and configure it in your nuxt.config:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/image'],
  image: {
    provider: 'cloudinary',
    cloudinary: {
      baseURL: 'https://res.cloudinary.com/<your-cloud-name>/image/upload',
    },
  },
})

The src of your images is then a path on the provider:

<template>
  <NuxtImg
    src="/blog/cover.jpg"
    alt="Blog post cover"
    width="800"
    height="450"
  />
</template>

You can also use a provider for a single image with the provider prop.

Next Steps

See the Nuxt Image documentation for all its features:

  • <NuxtImg>: all props of the image component.
  • <NuxtPicture>: serve several image formats.
  • useImage(): generate optimized image URLs in your code, for example for CSS backgrounds.
  • Configuration: set defaults such as quality, formats, screen sizes, and presets.