High-performance responsive/progressive images for SvelteKit.
Automatically transform local images into multiple widths and next-gen formats, then render a minimally invasive LQIP-included HTML representation into your SvelteKit project.
Includes special effects:
- Fade-in on image reveal
- Parallax vertical scroll effect
Hope you like cats. Demo: https://zerodevx.github.io/svelte-img/
Install the package:
$ npm i -D @zerodevx/svelte-img
Add imagetools plugin into your vite.config.js:
import { defineConfig } from 'vite'
import { sveltekit } from '@sveltejs/kit/vite'
import { imagetools } from '@zerodevx/svelte-img/vite'
export default defineConfig({
plugins: [sveltekit(), imagetools()]
})Optionally, to silence typescript
warnings on image imports, create a new
file at src/ambient.d.ts:
// Squelch warnings of image imports from your assets dir
declare module '$lib/assets/*' {
var meta
export default meta
}Local image transformations are delegated to the excellent
vite-imagetools with a custom run directive.
This preset generates optimised images with sensible defaults, including a base64 low-quality
image placeholder.
Invoke the preset with the ?as=run query param:
import imageMeta from 'path/to/asset?as=run'Use anywhere in your Svelte app:
<script>
// Import original full-sized image with `?as=run` query param
import cat from '$lib/assets/cat.jpg?as=run'
import Img from '@zerodevx/svelte-img'
</script>
<Img class="cool kitty" src="{cat}" alt="Very meow" />The image component renders into:
<picture>
<source
type="image/avif"
srcset="path/to/avif-480 480w, path/to/avif-1024 1024w, path/to/avif-1920 1920w"
/>
<source
type="image/webp"
srcset="path/to/webp-480 480w, path/to/webp-1024 1024w, path/to/webp-1920 1920w"
/>
<source
type="image/jpeg"
srcset="path/to/jpeg-480 480w, path/to/jpeg-1024 1024w, path/to/jpeg-1920 1920w"
/>
<img
class="cool kitty"
width="1920"
height="1080"
loading="lazy"
decoding="async"
style="background: url(data:image/webp;base64,XXX) no-repeat center/cover"
alt="Very meow"
src="path/to/jpeg-1920"
/>
</picture>By default, svelte-img generates 9 variants of an original full-sized image - at 480/1024/1920
widths in avif/webp/jpg formats; and a 16px webp/base64 low-quality image placeholder (LQIP).
To change this globally, edit your vite.config.js:
import ...
// By default, `run` is set to 'w=480;1024;1920&format=avif;webp;jpg' (9 variants)
export default defineConfig({
plugins: [
sveltekit(),
imagetools({
profiles: {
// Now we change `run` to generate 4 variants instead: 640/1280w in webp/jpg
run: new URLSearchParams('w=640;1280&format=webp;jpg')
}
})
]
})Note
runDefaultDirectives is deprecated and will be removed in the next major; use profiles
instead. When a profile is not used, behaviour falls back to standard vite-imagetools, which in
turn take defaults from defaultDirectives as usual, so both can co-exist.
Use profiles to manage multiple defaults. Define in your vite.config.js:
export default defineConfig({
plugins: [
sveltekit(),
imagetools({
profiles: {
sm: new URLSearchParams('w=640&format=webp;jpg'),
lg: new URLSearchParams('w=640;1280;1920&format=webp;jpg')
}
})
]
})Then invoke in your app:
import sm from '$lib/a/1.jpg?as=sm' // use `sm` profile
import lg from '$lib/a/2.jpg?as=lg' // use `lg` profile
import normal from '$lib/a/3.jpg?as=run'Widths/formats can be applied to a particular image. From your .svelte file:
<script>
// We override defaults to generate 4 variants: 720/1560w in webp/jpg
import src from '$lib/a/cat.jpg?w=720;1560&format=webp;jpg&as=run'
import Img from '@zerodevx/svelte-img'
</script>
<Img {src} alt="cat" />Note
Order of format matters - the last format is used as the fallback image.
If just one variant is generated, then only the <img> tag renders, so:
<script>
// Generate only 1 variant: 640x640 in jpg
import src from '$lib/a/cat.jpg?w=640&h=640&format=jpg&as=run'
import Img from '@zerodevx/svelte-img'
</script>
<Img {src} alt="cat" />Renders into:
<img
width="640"
height="640"
loading="lazy"
decoding="async"
style="background: url(data:image/webp;base64,XXX) no-repeat center/cover"
alt="cat"
src="path/to/jpg-640"
/>The run directive takes an optional parameter that sets the LQIP's width. Using ?as=run defaults
to 16px LQIP - functionally equivalent to ?as=run:16. Increase for a higher quality LQIP (eg.
?as=run:32 for 32px LQIP) at the expense of a larger inline base64 (larger HTML size).
To disable LQIP, set ?as=run:0.
For a dominant single-colour background, set ?as=run:1, so:
<script>
import src from '$lib/a/cat.jpg?as=run:1'
import Img from '@zerodevx/svelte-img'
</script>
<!-- Render img with dominant colour background -->
<Img {src} alt="cat" />Renders into:
<picture>
<source ... />
<img ... style="background: #abcdef" />
</picture>The full repertoire
of transformation directives offered by
vite-imagetools can be used.
<script>
// Generate all 9 variants at fixed 600px height
import src from '$lib/a/cat.jpg?h=600&fit=cover&normalize&as=run'
import Img from '@zerodevx/svelte-img'
</script>
<Img {src} alt="cat" />Use the sizes attribute to define media conditions that provide hints as to which image size to
select when those conditions are true. Read up more on
responsive images and the picture element.
<script>
import src from '$lib/a/cat.jpg?w=480;800&as=run'
import Img from '@zerodevx/svelte-img'
</script>
<!--
When the viewport is <=600px, tell the browser's image preloader that once
the CSS for our design has been parsed and applied, we expect the width of
the image in our design to be 480px.
-->
<img {src} alt="cat" sizes="(max-width: 600px) 480px, 800px" />Renders into:
<picture>
<source
type="image/avif"
sizes="(max-width: 600px) 480px, 800px"
srcset="path/to/avif-480 480w, path/to/avif-800 800w"
/>
<source
type="image/webp"
sizes="(max-width: 600px) 480px, 800px"
srcset="path/to/webp-480 480w, path/to/webp-800 800w"
/>
<source
type="image/jpeg"
sizes="(max-width: 600px) 480px, 800px"
srcset="path/to/jpeg-480 480w, path/to/jpeg-800 800w"
/>
<img
alt="cat"
width="800"
height="600"
loading="lazy"
decoding="async"
src="path/to/jpeg-800"
style="background: url(data:image/webp;base64,XXX) center center / cover no-repeat;"
/>
</picture>svelte-img utilises the browser's native lazy loading capability by setting the loading="lazy"
attribute on the rendered <img> tag by default. This is supported by
most modern browsers. To load an image eagerly instead:
<script>
import src from '$lib/a/cat.jpg?as=run'
import Img from '@zerodevx/svelte-img'
</script>
<Img {src} alt="cat" loading="eager" />Use Vite's import.meta.glob feature.
<script>
import Img from '@zerodevx/svelte-img'
const modules = import.meta.glob('$lib/a/cats/*.*', {
import: 'default',
eager: true,
query: { w: 640, h: 640, fit: 'cover', as: 'run' }
})
const images = Object.entries(modules).map((i) => i[1])
</script>
{#each images as src}
<Img {src} alt="cat" />
{/each}Use the svelte-img component on its own by passing a src object, like so:
<script>
import Img from '@zerodevx/svelte-img'
const src = {
sources: {
// Order is important; last format is fallback img
webp: 'path/to/480.webp 480w, ...', //srcset
jpeg: '...'
},
img: { src: 'path/to/img', w: 1920, h: 1080 },
}
</script>
<Img {src} alt="cat" />Natively, browsers do already apply some blur when displaying low resolution images. That's enough for me, but you can apply your own using CSS.
<script>
import Img from '@zerodevx/svelte-img'
import src from '$lib/a/cat.jpg?as=run'
import { onMount } from 'svelte'
let ref, loaded
onMount(() => {
if (ref.complete) loaded = true
})
</script>
<div class="wrap">
<Img {src} bind:ref on:load={() => (loaded = true)} />
<div class="blur" class:loaded />
</div>
<style>
.wrap {
position: relative;
overflow: hidden;
}
.blur {
position: absolute;
inset: 0;
backdrop-filter: blur(20px);
pointer-events: none;
}
.loaded {
display: none;
}
</style>Reveal images with a fade-in effect (aka medium.com) when they are loaded and in the viewport.
<script>
import src from '$lib/a/cat.jpg?as=run'
import { FxReveal as Img } from '@zerodevx/svelte-img'
</script>
<Img class="my-img" {src} alt="cat" />
<style>
:global(.my-img) {
width: 640px;
height: 480px;
/* These CSS vars (with their default values) are exposed */
--reveal-transform: scale(1.02);
--reveal-transition: opacity 1s ease-in, transform 0.8s ease-out;
--reveal-filter: blur(20px);
}
</style>Apply a vertical parallax scrolling effect to an image, where factor is a decimal value between 0
and 1, that controls how much slower the element scrolls, relative to the scrolling speed:
- A value closer to 0 is faster, while a value closer to 1 is slower.
- A value of 1 behaves normally.
- A value of 0 effectively makes the element fixed on the page.
The default factor is 0.75.
<script>
import src from '$lib/a/cat.jpg?as=run'
import { FxParallax as Img } from '@zerodevx/svelte-img'
</script>
<Img class="my-img" factor="0.5" {src} alt="cat" />
<style>
:global(.my-img) {
width: 100%;
height: 28rem;
}
</style>Library is packaged via SvelteKit. Standard Github contribution workflow applies.
End-to-end testing via Playwright. To run tests headlessly:
$ npm run test
Please refer to the releases page.
ISC