Nuxt Image

Nuxt Image provides plug-and-play image optimization for Nuxt applications. It allows you to resize and transform images using a built-in optimizer or an external Image CDN.

Key capabilities include:

• Using <nuxt-img> as a drop-in replacement for the native <img> element.
• Using <nuxt-picture> as a drop-in replacement for the native <picture> element.
• Built-in resizing and transformation via unjs/ipx.
• Support for over 20 different image providers.
• Automatic generation of responsive sizes.
• Optimization using modern formats like webp and avif.

The fit and position modifiers allow you to control how images are cropped and anchored.

Important: Both fit and position only take effect if the format modifier is set to webp.

Fit

Determines how the image fits within the specified dimensions. Valid values:

• cover (default)
• contain
• fill
• inside
• outside

Position

Determines the anchor point for cropping. Valid values:

• top
• right top
• right
• right bottom
• bottom
• left bottom
• left
• left top
• center (default)

Example usage:

<NuxtImg src="..." width="300" height="300" modifiers="{ fit: 'contain', format: 'webp' }" />
<NuxtImg src="..." width="300" height="300" modifiers="{ position: 'bottom left', format: 'webp' }" />

Nuxt Image maps its standard fit options to specific Sanity modifiers. Note the distinction between fill and contain to ensure expected behavior:

Important: For compatibility with other providers, fit: fill uses Sanity's scale behavior. If you require Sanity's ?fit=fill behavior, use fit: contain instead.

Presets allow you to define collections of pre-defined configurations (like modifiers) to unify image usage across your project. You can apply a preset to a component using the preset prop.

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

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

The modifiers object allows you to access Directus-specific features. There are two primary ways to use modifiers:

1. Direct Transforms: Use withoutEnlargement to prevent upscaling and transforms to pass a pipeline of Sharp operations.
2. Keyed Transforms: Use a key to reference a pre-configured Directus transform. Note: When using key, do not combine it with other modifiers.

Example: Pipeline of transforms

<NuxtImg
  provider="directus"
  :modifiers="{
    withoutEnlargement: true,
    transforms: [['blur', 4], ['negate']]
  }"
/>

Example: Keyed transform

<NuxtImg
  provider="directus"
  :modifiers="{
    key: 'system-large-cover'
  }"
/>

NOTE

Directus defaults ASSETS_TRANSFORM_MAX_OPERATIONS to 5. If you need more operations, it is recommended to use a keyed transform or update your Directus configuration.

Nuxt Image supports multiple providers to achieve high performance. A provider is an integration between Nuxt Image and a third-party image transformation service. Each provider is responsible for generating the correct URLs required by that specific service to perform image transformations.

Nuxt Image can be configured to use a specific provider or can be configured to work with any external image transformation service.

ImageKit provides additional cropping and resizing modes via the fit property that extend the standard Nuxt Image options:

• extract: The output image maintains the requested height and width while preserving the aspect ratio. It extracts a specific region from the original image.
• pad_extract: Similar to extract, but if the requested dimension is larger than the original image, it adds solid colored padding to match the requested size.

Refer to ImageKit's documentation for detailed crop mode behaviors.