Configuration

To configure the image module and customize its behavior, you can use the image property in your nuxt.config:

export default defineNuxtConfig({
  image: {
    // Options
  }
})

inject

By default Nuxt Image v1 adopts a composable approach. If you do not use the components no additional code will be added to your bundle. But if you wish to globally initialize an $img helper that will be available throughout your application, you can do so.

export default defineNuxtConfig({
  image: {
    inject: true
  }
})

quality

The quality for the generated image(s).

You can also override this option at the component level by using the quality prop.

export default defineNuxtConfig({
  image: {
    quality: 80
  }
})

format

Default: ['webp']

You can use this option to configure the default format for your images used by <NuxtPicture>. The available formats are webp, avif, jpeg, jpg, png, and gif. The order of the formats is important, as the first format that is supported by the browser will be used. You can pass multiple values like ['avif', 'webp'].

You can also override this option at the component level by using the format prop.

export default defineNuxtConfig({
  image: {
    format: ['webp']
  }
})

screens

List of predefined screen sizes.

These sizes will be used to generate resized and optimized versions of an image (for example, with the sizes modifier).

export default defineNuxtConfig({
  image: {
    // The screen sizes predefined by `@nuxt/image`:
    screens: {
      'sm': 640,
      'md': 768,
      'lg': 1024,
      'xl': 1280,
      '2xl': 1536
    }
  }
})

domains

To enable image optimization on an external website, specify which domains are allowed to be optimized. This option will be used to detect whether a remote image should be optimized or not. This is needed to ensure that external URLs can't be abused.

export default defineNuxtConfig({
  image: {
    domains: ['nuxtjs.org']
  }
})

presets

Presets are collections of pre-defined configurations for your projects. Presets will help you to unify images all over your project.

export default defineNuxtConfig({
  image: {
    presets: {
      avatar: {
        modifiers: {
          format: 'jpg',
          width: 50,
          height: 50
        }
      }
    }
  }
})

<template>
  <NuxtImg
    preset="avatar"
    src="/nuxt-icon.png"
  />
</template>

providers

In order to create and use a custom provider, you need to use the providers option and define your custom providers.

export default defineNuxtConfig({
  image: {
    providers: {
      random: {
        provider: '~/providers/random',
        options: {}
      }
    }
  }
})

<template>
  <NuxtImg
    provider="random"
    src="main.png"
    width="300"
    height="169"
  />
</template>

provider

Default: ipx (or ipxStatic if used with a static nitro preset, such as if you are running nuxt generate)

We can specify default provider to be used when not specified in component or when calling $img.

export default defineNuxtConfig({
  image: {
    provider: 'twicpics',
    twicpics: {
      baseURL: 'https://nuxt-demo.twic.pics'
    }
  }
})

modifiers

You can set default modifiers for the selected provider.

export default defineNuxtConfig({
  image: {
    provider: 'cloudinary',
    cloudinary: {
      baseURL: 'https://res.cloudinary.com/<company>/image/fetch',
      modifiers: {
        effect: 'sharpen:100',
        quality: 'auto:best'
      }
    }
  }
})

densities

Default: [1, 2]

Specify a value to work with devicePixelRatio > 1 (these are devices with retina display and others). You must specify for which devicePixelRatio values you want to adapt images.

You can read more about devicePixelRatio on MDN.

export default defineNuxtConfig({
  image: {
    densities: [1, 2, 3]
  }
})

dir

Default: public

This option allows you to specify the location of the source images when using the ipx or ipxStatic provider.

For example you might want the source images in assets/images directory rather than the default public directory so the source images don't get copied into dist and deployed:

export default defineNuxtConfig({
  image: {
    dir: 'assets/images'
  }
})

Notes:

• For ipxStatic provider, if images weren't crawled during generation (unreachable modals, pages or dynamic runtime size), changing dir from public causes 404 errors.
• For ipx provider, make sure to deploy customized dir as well.
• For some providers (like vercel), using a directory other than public/ for assets is not supported since resizing happens at runtime (instead of build/generate time) and source fetched from the public/ directory (deployment URL)

alias

This option allows you to specify aliases for src.

When using the default ipx provider, URL aliases are shortened on the server-side. This is especially useful for optimizing external URLs and not including them in HTML.

When using other providers, aliases are resolved in runtime and included in HTML. (only the usage is simplified)

Example:

export default defineNuxtConfig({
  image: {
    domains: [
      'images.unsplash.com'
    ],
    alias: {
      unsplash: 'https://images.unsplash.com'
    }
  }
})

Before using alias:

<NuxtImg src="https://images.unsplash.com/<id>" />

Generates:

<img src="/_ipx/https://images.unsplash.com/<id>">

After using alias:

<NuxtImg src="/unsplash/<id>" />

Generates:

<img src="/_ipx/unsplash/<id>">

Both usage and output are simplified!