Nuxt Image Optimization — Complete Guide to @nuxt/image

In this tutorial, you will learn about Nuxt Image Optimization. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Nuxt image optimization with @nuxt/image module — responsive images, WebP conversion, Lazy Loading, and custom providers for faster page loads.

In this lesson, you'll understand how to use the Nuxt Image module to automatically optimize images, generate responsive sizes, and serve modern formats.

What You'll Learn

How to install and configure @nuxt/image, use the NuxtImg and NuxtPicture components, set up image providers, and optimize images for performance.

Why It Matters

Images are the largest contributor to page weight — often 50-60% of total bytes. Optimizing them reduces load times, improves Core Web Vitals (LCP), and boosts SEO rankings.

Real-World Use

An e-commerce site with product images drops load time from 4.2s to 1.8s by using Nuxt Image with WebP conversion, lazy loading, and responsive sizes — directly improving conversion rates.

flowchart LR
    A[Source Image] --> B[NuxtImg Component]
    B --> C[Responsive Sizes]
    B --> D[WebP/AVIF]
    B --> E[Lazy Loading]
    C --> F[Optimized Output]
    D --> F
    E --> F
    F --> G[Faster LCP]
    F --> H[Lower Bandwidth]
    style A fill:#00dc82,color:#fff

Installation and Setup

Install the module and add it to your Nuxt config:

npm install @nuxt/image

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/image'],
  image: {
    // Default provider
    provider: 'ipx',
    // Screens breakpoints
    screens: {
      xs: 320,
      sm: 640,
      md: 768,
      lg: 1024,
      xl: 1280,
      xxl: 1536
    }
  }
});

Using NuxtImg

The NuxtImg component generates optimized <img> tags:

<template>
  <NuxtImg
    src="/images/hero.jpg"
    alt="Hero banner"
    width="1200"
    height="600"
    loading="lazy"
    format="webp"
    densities="x1 x2"
  />
</template>

Expected output: HTML <img> with srcset for multiple resolutions, loading="lazy", and automatic WebP conversion.

Responsive Images with Sizes

Control which image size loads at each breakpoint:

<template>
  <NuxtImg
    src="/images/landscape.jpg"
    alt="Landscape photo"
    sizes="sm:300px md:600px lg:900px xl:1200px"
    :modifiers="{ brightness: 1.1, contrast: 1.2 }"
  />
</template>

Expected output: Different image sizes load depending on viewport, reducing bandwidth on mobile devices.

Using NuxtPicture

For more control with <picture> element and multiple formats:

<template>
  <NuxtPicture
    src="/images/photo.jpg"
    alt="Gallery photo"
    :imgAttrs="{ class: 'rounded-lg', decoding: 'async' }"
    format="avif"
    loading="lazy"
  />
</template>

Expected output: <picture> element with AVIF and WebP fallbacks, browser chooses the best format.

Remote Images and Providers

Configure external image sources:

// nuxt.config.ts
export default defineNuxtConfig({
  image: {
    providers: {
      cloudinary: {
        provider: 'cloudinary',
        options: {
          baseURL: 'https://res.cloudinary.com/my-cloud/image/upload'
        }
      },
      customProvider: {
        provider: '~/providers/custom.ts',
        options: {
          baseURL: 'https://images.example.com'
        }
      }
    }
  }
});

<template>
  <!-- Remote image with Cloudinary provider -->
  <NuxtImg
    provider="cloudinary"
    src="/v1/my-image.jpg"
    width="800"
    height="600"
    :modifiers="{ quality: 80, effect: 'sharpen' }"
  />
</template>

Placeholder and Blur-Up Images

Show a low-quality placeholder while the full image loads:

<template>
  <NuxtImg
    src="/images/large-banner.jpg"
    alt="Large banner"
    placeholder
    width="1600"
    height="900"
  />
</template>

Expected output: A tiny blurred version loads first, then transitions smoothly to the full image as it loads.

Common Mistakes

1. Not setting explicit width and height: Without dimensions, the browser cannot reserve space, causing Cumulative Layout Shift (CLS) and hurting your Lighthouse score.

2. Forgetting to add loading="lazy": Images below the fold should lazy load. Without it, the browser downloads all images upfront, slowing initial page load.

3. Using local images without the static directory: Place images in the public/ directory or use the assets/ directory with a path alias. Referencing files outside these directories causes 404 errors.

4. Not configuring screens for responsive images: Without screens, Nuxt Image doesn't know which breakpoints to generate. The default set may not match your CSS breakpoints.

5. Overriding the provider incorrectly: When switching between local and remote providers, the baseURL must match. A mismatch produces broken image URLs with no error message.

Practice Questions

1. What does the sizes prop on NuxtImg control? Answer: It defines which image dimensions load at different viewport breakpoints, enabling responsive image delivery.

2. How does the format prop affect the output? Answer: It sets the target image format (WebP, AVIF). The browser receives the best supported format. The default behavior converts to WebP automatically.

3. What is the purpose of the placeholder prop? Answer: It generates a tiny blurred image that displays immediately while the full image loads, improving perceived performance.

4. How do you configure a custom image provider? Answer: Add a provider object under image.providers in nuxt.config.ts with a baseURL and optional provider module.

Challenge

Build a responsive image gallery with NuxtImg that: uses three different providers (local, Cloudinary, and a custom provider), implements lazy loading with placeholders, generates four responsive sizes per image, and shows the active format using the browser's native picture element support detection.

Mini Project

Create an image-optimized landing page for a photography portfolio. Include: a hero image with responsive sizes using NuxtPicture, a gallery grid with lazy loading and placeholders, WebP conversion with AVIF fallback, and a comparison of page weight before and after optimization using the Network tab.

FAQ

What's Next

Learn about Nuxt Content Management to manage markdown-based content in your Nuxt application with the @nuxt/content module.