Magic Image is a Nuxt module that combines Nuxt Image and Unlazy into a single component with automatic lazy loading, responsive srcsets, and built-in support for the MaaS and Mux image providers.
- Auto lazy loading — Native lazy loading via Unlazy with SSR placeholder support
- Responsive srcsets — Automatic multi-size srcset generation via Nuxt Image
- Built-in providers — MaaS image CDN and Mux video thumbnail extraction out of the box
- Typed modifiers — Full TypeScript types for all provider-specific modifier options
Install the package and its peer dependencies:
# npm
npm install @maas/magic-image @nuxt/image @unlazy/nuxt
# pnpm
pnpm add @maas/magic-image @nuxt/image @unlazy/nuxt
# yarn
yarn add @maas/magic-image @nuxt/image @unlazy/nuxtTip: This package ships with an
.npmrcthat setsauto-install-peers=true. With pnpm, this means@nuxt/imageand@unlazy/nuxtare installed automatically alongside@maas/magic-image— a singlepnpm add @maas/magic-imageis enough. npm 7+ auto-installs peer deps by default too. Yarn always requires manual peer dep installation as shown above.
Register the module in your nuxt.config.ts:
export default defineNuxtConfig({
modules: ['@maas/magic-image'],
magicImage: {
// Default srcset breakpoints (optional)
sizes: '128w:128px 512w:512px 720w:720px 1024w:1024px 1440w:1440px',
// Passed to @nuxt/image — see https://image.nuxt.com/get-started/configuration
image: {
provider: 'maas',
},
// Passed to @unlazy/nuxt — see https://unlazy.byjohann.dev/integrations/nuxt.html
unlazy: {
ssr: true,
},
},
})The <MagicImage> component is registered globally — no import needed.
<template>
<MagicImage
src="https://images.unsplash.com/photo-1694444070793-13db645409f4"
:modifiers="{ width: 800, height: 600, fit: 'cover' }"
/>
</template>| Prop | Type | Default | Description |
|---|---|---|---|
src |
string |
— | Image source URL (required) |
provider |
string |
module default | Provider name ('maas', 'mux', or any Nuxt Image provider) |
modifiers |
Partial<MagicImageModifiers> |
— | Provider-specific image transformations |
sizes |
string | Record<string, string | number> |
module default | Responsive size breakpoints |
preset |
string |
— | Nuxt Image preset name |
densities |
string |
— | Device density descriptors (e.g. '1x 2x') |
placeholderSrc |
string |
1×1 GIF | Placeholder shown while loading |
preload |
boolean |
false |
Add <link rel="preload"> to <head> |
autoSizes |
boolean |
true |
Auto-compute sizes attribute |
lazyload |
boolean |
true |
Enable lazy loading |
| Event | Description |
|---|---|
loaded |
Fired when the image has finished loading |
Built-in provider for the MaaS image CDN. Set provider: 'maas' (or use it as the default provider) and pass any of the supported modifiers:
<MagicImage
src="https://images.unsplash.com/photo-1694444070793-13db645409f4"
provider="maas"
:modifiers="{
width: 800,
height: 600,
fit: 'cover',
format: 'webp',
quality: 80,
}"
/>MaaS modifiers:
| Modifier | Type | Description |
|---|---|---|
width |
number |
Output width in px |
height |
number |
Output height in px |
fit |
'cover' | 'contain' | 'fill' | 'inside' | 'outside' |
Resize fit mode |
format |
'jpg' | 'jpeg' | 'png' | 'webp' |
Output format |
quality |
number |
Output quality (1–100) |
pixelDensity |
number |
Device pixel ratio (e.g. 2 for 2×) |
blur |
number |
Blur radius |
sharpen |
number |
Sharpening strength |
brightness |
number |
Brightness adjustment |
contrast |
number |
Contrast adjustment |
saturation |
number |
Saturation adjustment |
hue |
number |
Hue rotation in degrees |
gamma |
number |
Gamma correction |
filter |
'greyscale' | 'sepia' | 'negative' | 'duotone' |
Color filter |
rotate |
number |
Rotation in degrees |
mirror |
boolean |
Flip horizontally |
mask |
'circle' | 'ellipse' | 'triangle' | 'pentagon' | 'hexagon' | 'square' | 'star' | 'heart' | … |
Shape mask |
background |
string |
Background color |
trimImage |
boolean |
Auto-trim whitespace |
Built-in provider for Mux video thumbnail extraction. Pass the full Mux thumbnail URL as src and set provider="mux":
<MagicImage
src="https://image.mux.com/YOUR_PLAYBACK_ID/thumbnail.jpg"
provider="mux"
:modifiers="{
width: 1280,
height: 720,
fit: 'cover',
time: 12,
}"
/>Mux modifiers:
| Modifier | Type | Description |
|---|---|---|
width |
number |
Thumbnail width in px |
height |
number |
Thumbnail height in px |
fit |
'cover' | 'contain' | 'fill' | 'pad' | 'smartcrop' |
Resize fit mode |
time |
number |
Timestamp in seconds to extract thumbnail from |
rotate |
number |
Rotation in degrees |
flipHorizontal |
boolean |
Flip horizontally |
flipVertical |
boolean |
Flip vertically |
start |
number |
Clip start time |
end |
number |
Clip end time |
fps |
number |
Frames per second (for animated thumbnails) |
Import MagicImageModifiers for typed modifier objects:
import type { MagicImageModifiers } from '@maas/magic-image'
const modifiers: Partial<MagicImageModifiers> = {
width: 800,
format: 'webp',
filter: 'greyscale',
}MIT License © 2024-PRESENT Magic as a Service GmbH