Configuration

Nuxt Image is configured with sensible defaults.

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

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

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: {
      xs: 320,
      sm: 640,
      md: 768,
      lg: 1024,
      xl: 1280,
      xxl: 1536,
      '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>
  <nuxt-img 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>
  <nuxt-img provider="random" src="main.png" width="300" height="169" />
</template>

provider

Default: static

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',
      }
    }
  }
})

staticFilename

You can use this option to change filename and location for the static image generation.

Parameters

• [name]: Only filename, without extension or path
• [hash]: The hash of url
• [ext]: Extension with leading dot .png
• [publicPath]: Default is build.publicPath (/_nuxt)

export default defineNuxtConfig({
  image: {
      // Generate images to `/_nuxt/images/file.png`
      staticFilename: '[publicPath]/images/[name]-[hash][ext]'
  }
})

dir

Default: static

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

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

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

Notes:

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

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

Generates:

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

After using alias:

<nuxt-img src="/unsplash/<id>" />

Generates:

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

Both usage and output are simplified!