---
title: "Configuration"
description: "Nuxt Image is configured with sensible defaults."
canonical_url: "https://nuxt.com/modules/image/configuration"
---
# 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`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  image: {
    // Options
  }
})
```

## `inject`

By default Nuxt Image 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.

```ts [nuxt.config.ts]
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](https://nuxt.com/modules/image/usage/nuxt-img#quality).

```ts [nuxt.config.ts]
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](https://nuxt.com/modules/image/usage/nuxt-picture#format).

```ts [nuxt.config.ts]
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`](https://nuxt.com/modules/image/usage/nuxt-img#sizes) modifier).

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

::note
By default, we share the same naming and sizes as [Tailwind CSS](https://tailwindcss.com/docs/responsive-design). If you need a list of screen sizes matching a different framework, check out [VueUse breakpoint presets](https://vueuse.org/core/useBreakpoints/#presets).
::

## `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.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  image: {
    domains: ['nuxt.com']
  }
})
```

## `presets`

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

::code-group
```ts [nuxt.config.ts]
export default defineNuxtConfig({
  image: {
    presets: {
      avatar: {
        modifiers: {
          format: 'jpg',
          width: 50,
          height: 50
        }
      }
    }
  }
})
```

```vue [index.vue]
<template>
  <NuxtImg
    preset="avatar"
    src="/nuxt-icon.png"
  />
</template>
```
::

## `providers`

In order to create and use a [custom provider](https://nuxt.com/modules/image/advanced/custom-provider), you need to use the `providers` option and define your custom providers.

::code-group
```ts [nuxt.config.ts]
export default defineNuxtConfig({
  image: {
    providers: {
      random: {
        provider: '~/providers/random',
        options: {}
      }
    }
  }
})
```

```vue [index.vue]
<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`.

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

### `modifiers`

You can set default modifiers for the selected provider.

```ts [nuxt.config.ts]
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](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio).

```ts [nuxt.config.ts]
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:

```ts [nuxt.config.ts]
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:**

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

**Before** using alias:

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

Generates:

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

**After** using alias:

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

Generates:

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

Both usage and output are simplified!


## Sitemap

See the full [sitemap](https://nuxt.com/sitemap.md) for all pages.