svelte-img

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

Install the package:

$ npm i -D @zerodevx/svelte-img

Add imagetools plugin into your vite.config.js:

jsCopy
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:

jsCopy
// Squelch warnings of image imports from your assets dir
declare module '$lib/assets/*' {
  var meta
  export default meta
}

Under the hood

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:

jsCopy
import imageMeta from 'path/to/asset?as=run'

Usage

Use anywhere in your Svelte app:

<!-- prettier-ignore -->

htmlCopy
<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:

htmlCopy
<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>

Features

Change default widths/formats

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:

jsCopy
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.

Profiles

Use profiles to manage multiple defaults. Define in your vite.config.js:

jsCopy
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:

jsCopy
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'

On a per-image basis

Widths/formats can be applied to a particular image. From your .svelte file:

<!-- prettier-ignore -->

htmlCopy
<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:

<!-- prettier-ignore -->

htmlCopy
<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:

htmlCopy
<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"
/>

Change LQIP width

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:

<!-- prettier-ignore -->

htmlCopy
<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:

<!-- prettier-ignore -->

htmlCopy
<picture>
  <source ... />
  <img ... style="background: #abcdef" />
</picture>

Other transformations

The full repertoire
of transformation directives offered by
vite-imagetools can be used.

<!-- prettier-ignore -->

htmlCopy
<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" />

Responsive Image Sizes

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.

htmlCopy
<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:

htmlCopy
<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>

Lazy loading

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:

<!-- prettier-ignore -->

htmlCopy
<script>
  import src from '$lib/a/cat.jpg?as=run'
  import Img from '@zerodevx/svelte-img'
</script>

<Img {src} alt="cat" loading="eager" />

Batch loading local images

Use Vite's import.meta.glob feature.

<!-- prettier-ignore -->

htmlCopy
<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}

Remote images from an API

Use the svelte-img component on its own by passing a src object, like so:

<!-- prettier-ignore -->

htmlCopy
<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" />

Blurred image placeholders

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.

<!-- prettier-ignore -->

htmlCopy
<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>

Special Effects

Fade-in on reveal

Reveal images with a fade-in effect (aka medium.com) when they are loaded and in the viewport.

<!-- prettier-ignore -->

htmlCopy
<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>

Parallax

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.

<!-- prettier-ignore -->

htmlCopy
<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>

Development

Library is packaged via SvelteKit. Standard Github
contribution workflow
applies.

Tests

End-to-end testing via Playwright. To run tests
headlessly:

$ npm run test

Changelog

Please refer to the releases page.

License

ISC