Usage of <nuxt-img> component
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
- Support
loading="lazy"
for wider range of browsers including Safari using IntersectionObserver - Generates responsive sizes when providing
sizes
option
Use it like you would use the <img>
tag:
<nuxt-img src="/nuxt-icon.png" />
Will result in:
<img src="/nuxt-icon.png" alt="nuxt-icon" />
Props
src
Path to image file
src
should be in the form of an absolute path for static images in static/
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 reiszes.
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>
export default {
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.
nuxt.config
<template>
<nuxt-img preset="jpg-cover" src="/nuxt-icon.png" width="50" height="50" />
</template>
export default {
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.
<nuxt-img format="webp" src="/nuxt-icon.png" ... />
Available formats are webp
, 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 standard modifiers, every provider can have their own modifiers.
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' }"
/>