<nuxt-img>
Discover how to use and configure the nuxt-img component.
<nuxt-img>
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
andheight
- Generates responsive sizes when providing
sizes
option - Supports native lazy loading as well as other
<img>
attributes
Usage
nuxt-img
outputs a native img
tag directly (without any wrapper around it). Use it like you would use the <img>
tag:
<nuxt-img src="/nuxt-icon.png" />
Will result in:
<img src="/nuxt-icon.png" />
/nuxt-icon.png
inside public/
directory for Nuxt 3 make the above example work.Props
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.
<nuxt-img 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
)
sizes
Specify responsive sizes.
This a space-separated list of screen size/width pairs. You can see a list of the defined screen sizes here).
Example:
<nuxt-img
src="/logos/nuxt.png"
sizes="sm:100vw md:50vw lg:400px"
/>
provider
Use other provider instead of default provider option specified in nuxt.config
Example:
<template>
<nuxt-img
provider="cloudinary"
src="/remote/nuxt-org/blog/going-full-static/main.png"
width="300"
height="169"
/>
</template>
preset
Presets are predefined sets of image modifiers that can be used create unified form of images in your projects.
nuxt.config
<template>
<nuxt-img preset="cover" src="/nuxt-icon.png" />
</template>
format
In case you want to serve images in a specific format, use this prop.
<nuxt-img 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).
<nuxt-img 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 fitcontain
: 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.
<nuxt-img fit="cover" src="/nuxt-icon.png" width="200" height="100" />
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:
<nuxt-img
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.
<nuxt-img preload src="/nuxt-icon.png" />
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.
<nuxt-img src="/nuxt-icon.png" loading="lazy" />
Events
Native events emitted by the <img>
element contained by <nuxt-img>
and <nuxt-picture>
components are re-emitted and can be listened to.
Example: Listen to the native onLoad
event from <nuxt-img>
<nuxt-img
src="/images/colors.jpg"
width="500"
height="500"
@load="doSomethingOnLoad"
/>