Skip to content

1.nuxt-img.md

Latest commit

 

History

History
423 lines (318 loc) · 11.7 KB

1.nuxt-img.md

File metadata and controls

423 lines (318 loc) · 11.7 KB
title <NuxtImg>
description Discover how to use and configure the Nuxt Image component.
links
label icon to size
Source
i-simple-icons-github
xs

<NuxtImg> is a drop-in replacement for the native <img> tag.

  • Uses built-in provider to optimize local and remote images
  • Converts src to provider optimized URLs
  • Automatically resizes images based on width and height
  • Generates responsive sizes when providing sizes option
  • Supports native lazy loading as well as other <img> attributes

Usage

<NuxtImg> outputs a native img tag directly (without any wrapper around it). Use it like you would use the <img> tag:

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

Will result in:

<img src="/nuxt-icon.png">

::note With default provider, you should put /nuxt-icon.png inside public/ directory for Nuxt 3 make the above example work. ::

Props

custom

The custom prop determines whether <NuxtImg> should render as a simple <img> element or only serve as a provider for custom rendering. When set to true, it disables the default rendering behavior, allowing full control over how the image is displayed. This is useful for implementing custom functionalities, such as placeholders.

When using the custom prop, <NuxtImg> passes necessary data and attributes to its default slot. You can access the following values via the v-slot directive:

  • imgAttrs: Attributes for the <img> element (e.g., alt, width, height, srcset, sizes).
  • src: The computed image source URL.
  • isLoaded: A boolean indicating whether the image has been loaded.

Example Usage

<NuxtImg
  src="/images/nuxt.png"
  alt="image"
  width="400"
  height="400"
  :custom="true"
  v-slot="{ src, isLoaded, imgAttrs }"
>
  <!-- Show the actual image when loaded -->
  <img
    v-if="isLoaded"
    v-bind="imgAttrs"
    :src="src"
  >

  <!-- Show a placeholder while loading -->
  <img
    v-else
    src="https://placehold.co/400x400"
    alt="placeholder"
  >
</NuxtImg>

This approach ensures flexibility for custom rendering scenarios, while <NuxtImg> continues to handle image optimization and data provisioning behind the scenes.

src

Path to image file

src should be in the form of an absolute path for static images in public/ directory. Otherwise path that is expected by provider that starts with / or a URL.

<NuxtImg src="/nuxt.png" />

For image optimization when using external URLs in src, we need to whitelist them using domains option.

width / height

Specify width/height of the image.

  • Use desired width/height for static sized images like icons or avatars
  • Use original image width/height for responsive images (when using sizes)

alt

Although Nuxt Image does not apply any special handling, it's worth mentioning the alt attribute. It is a native global attribute that specifies an alternate text for an image, if the image cannot be displayed.

It should always be provided.

  • The text should describe the image if the image contains information
  • The text should explain where the link goes if the image is inside an <a> element
  • Use alt="" if the image is only for decoration
<NuxtImg
  src="/nuxt.png"
  alt="My image file description"
/>

sizes

Specify responsive sizes.

This is a space-separated list of screen size/width pairs. You can see a list of the defined screen sizes here.

By default Nuxt generates responsive-first sizing.

  • If you omit a screen size prefix (like sm:) then this size is the 'default' size of the image. Otherwise, Nuxt will pick the smallest size as the default size of the image.
  • This default size is used up until the next specified screen width, and so on. Each specified size pair applies up - so md:400px means that the image will be sized 400px on md screens and up.

Example:

<NuxtImg
  src="/logos/nuxt.png"
  sizes="100vw sm:50vw md:400px"
/>

densities

The densities prop serves high-resolution images for Retina/HiDPI screens.

Nuxt Image generates multiple versions at different pixel densities and creates the appropriate srcset.

When you specify densities, Nuxt Image multiplies your base dimensions by each density value to generate the corresponding image sizes.

Example:

<!-- Small icon, sharp on all screen densities -->
<NuxtImg 
  src="/nuxt.png"
  height="50"
  densities="x1 x2"
/>

Will result in:

<!-- Rendered HTML -->
<img
  src="/_ipx/w_50/nuxt.png"
  srcset="/_ipx/w_50/nuxt.png 1x,
          /_ipx/w_100/nuxt.png 2x"
/>

placeholder

Display a placeholder image before the actual image is fully loaded.

You can also use the custom prop to make any placeholder you want.

The placeholder prop can be either a string, a boolean, a number, or an array. The usage is shown below for each case.

<!-- Automatically generate a placeholder based on the original image -->
<NuxtImg src="/nuxt.png" placeholder />

<!-- Set a width, height for the automatically generated placeholder  -->
<NuxtImg src="/nuxt.png" :placeholder="[50, 25]" />

<!-- Set a width, height, quality & blur for the automatically generated placeholder  -->
<NuxtImg src="/nuxt.png" :placeholder="[50, 25, 75, 5]" />

<!-- Set the width & height of the automatically generated placeholder, image will be a square -->
<NuxtImg src="/nuxt.png" :placeholder="15" />

<!-- Provide your own image -->
<NuxtImg src="/nuxt.png" placeholder="./placeholder.png" />

You can also leverage useImage() to generate a placeholder image based on the original image, can be useful if the source is an SVG or you want better control on the modifiers:

<template>
  <NuxtImg
    src="/nuxt.svg"
    :placeholder="img(`/nuxt.svg`, { h: 10, f: 'png', blur: 2, q: 50 })"
  />
</template>

<script setup lang="ts">
const img = useImage()
</script>

placeholder-class

When using a placeholder, you can use placeholder-class to apply a class to the original underlying <img> element (while the placeholder is being rendered).

<!-- Apply a static class to the original image -->
<NuxtImg
  src="/nuxt.png"
  placeholder
  placeholder-class="custom"
/>

<!-- Apply a dynamic class to the original image -->
<NuxtImg
  src="/nuxt.png"
  placeholder
  :placeholder-class="custom"
/>

::tip If you need to apply some CSS to only the loaded image you can do so with something like:

img:not(.my-placeholder-class) {
  /* styles here */
}

::

provider

Use other provider instead of default provider option specified in nuxt.config

Example:

::code-group

<template>
  <NuxtImg
    provider="cloudinary"
    src="/remote/nuxt-org/blog/going-full-static/main.png"
    width="300"
    height="169"
  />
</template>
export default defineNuxtConfig({
  image: {
    cloudinary: {
      baseURL: 'https://res.cloudinary.com/nuxt/image/upload'
    }
  }
})

::

preset

Presets are predefined sets of image modifiers that can be used create unified form of images in your projects.

::note We can define presets using presets options in nuxt.config ::

::code-group

<template>
  <NuxtImg preset="cover" src="/nuxt-icon.png" />
</template>
export default defineNuxtConfig({
  image: {
    presets: {
      cover: {
        modifiers: {
          fit: 'cover',
          format: 'jpg',
          width: 300,
          height: 300
        }
      }
    }
  }
})

::

format

In case you want to serve images in a specific format, use this prop.

<NuxtImg
  format="webp"
  src="/nuxt-icon.png"
/>

Available formats are webp, avif, jpeg, jpg, png, gif and svg. If the format is not specified, it will respect the default image format.

quality

The quality for the generated image(s).

<NuxtImg
  src="/nuxt.jpg"
  quality="80"
  width="200"
  height="100"
/>

fit

The fit property specifies the size of the images. There are five standard values you can use with this property.

  • cover: (default) Preserving aspect ratio, ensure the image covers both provided dimensions by cropping/clipping to fit
  • contain: Preserving aspect ratio, contain within both provided dimensions using 'letterboxing' where necessary.
  • fill: Ignore the aspect ratio of the input and stretch to both provided dimensions.
  • inside: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
  • outside: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified.
<NuxtImg
  fit="cover"
  src="/nuxt-icon.png"
  width="200"
  height="100"
/>

::note Some providers support other values. ::

modifiers

In addition to the standard modifiers, each provider might have its own additional modifiers. Because these modifiers depend on the provider, refer to its documentation to know what can be used.

Using the modifiers prop lets you use any of these transformations.

Example:

<NuxtImg
  provider="cloudinary"
  src="/remote/nuxt-org/blog/going-full-static/main.png"
  width="300"
  height="169"
  :modifiers="{ roundCorner: '0:100' }"
/>

preload

In case you want to preload the image, use this prop. This will place a corresponding link tag in the page's head.

<NuxtImg src="/nuxt-icon.png" preload />

loading

This is a native attribute that provides a hint to the browser on how to handle the loading of an image which is outside the viewport. It is supported by the latest version of all major browsers since March 2022.

Set loading="lazy" to defer loading of an image until it appears in the viewport.

<NuxtImg src="/nuxt-icon.png" loading="lazy" />

nonce [DEPRECATED]

This is a native global attribute that defines a cryptographic nonce (number used once) that can be used by Content Security Policy to determine whether or not a given fetch will be allowed to proceed for a given element. Providing a nonce allows you to avoid using the CSP unsafe-inline directive, which would allowlist all inline script or styles.

<template>
  <NuxtImg
    src="/nuxt-icon.png"
    :nonce="nonce"
  />
</template>

<script setup lang="ts">
// useNonce is not provided by @nuxt/image but might be
// provided by another module, for example nuxt-security
const nonce = useNonce()
</script>

::warning This property was available in Nuxt Image v1, but is deprecated in Nuxt Image v2.

Having nonce be configurable introduces significant security risks as there is no guarantee the provided nonce is cryptographfically secure, generated according to the specification, and unique across the app.

It's best to let battle-tested security modules like Nuxt Security handle the nonce generation.
::

Events

Native events emitted by the <img> element contained by <NuxtImg> and <NuxtPicture> components are re-emitted and can be listened to.

Example: Listen to the native onLoad event from <NuxtImg>

<NuxtImg
  src="/images/colors.jpg"
  width="500"
  height="500"
  @load="doSomethingOnLoad"
/>