slimmage

Getting Started

Install, import, done. One function call per image.

npm install slimmage-core

import { createSlimmage } from 'slimmage-core';

const cleanup = createSlimmage(img, {
  src: 'https://cdn.example.com/photo.jpg?width=160&quality=85',
  container: '.card',
});
// Later: cleanup();

import { useSlimmage } from 'slimmage-react';

function Photo({ url }) {
  const ref = useSlimmage({ src: url });
  return <img ref={ref} />;
}

<script>
  import { SlimmageImg } from 'slimmage-svelte';
</script>

<SlimmageImg src={url} />

import 'slimmage-wc';

<slimmage-img
  src="https://cdn.example.com/photo.jpg
       ?width=160&quality=85"
></slimmage-img>

Drag to Resize

The image URL updates based on the container width — not the viewport. Width is snapped to the nearest 160px step for CDN cacheability. Drag the handle to see it in action.

Layout Stability

Without an aspect-ratio hint, content below the image shifts when the image loads. Slimmage sets aspect-ratio on the img element to reserve the correct space before loading.

Click to clear and reload both images. Watch the content position in the left panel.

Dynamic Grid

Each grid cell is an independent container. Change the column count and each image adapts to its own cell width.

Ratchet: Never Re-download

Once a larger image is loaded, shrinking the container doesn't trigger a smaller request. The browser's cached image renders at the smaller size for free.

Below-Resolution: maxWidth

What happens when the container grows past the source image's native resolution? Set maxWidth to your source image's pixel width to cap requests. Without it, the CDN would upscale or serve the original at sizes that add bytes without adding detail.

createSlimmage(img, {
  src: 'https://cdn.example.com/photo.jpg?width=160&quality=85',
  maxWidth: 800,  // source image is 800px wide
  onBeforeLoad: (info) => {
    el.classList.toggle('below-res',
      info.requestedWidth >= 800);
  },
});

Background Images: CSS Container Queries

For responsive backgrounds, CSS container queries are the right tool. They switch images during the layout pass — zero JS delay, no flash of wrong-size content. Slimmage stays focused on <img> elements where CSS has no solution.

.hero {
  container-type: inline-size;
  container-name: hero;
}

.hero-bg {
  background-image: url('photo.jpg?width=480');
}

@container hero (min-width: 480px) {
  .hero-bg {
    background-image: url('photo.jpg?width=800');
  }
}

@container hero (min-width: 800px) {
  .hero-bg {
    background-image: url('photo.jpg?width=1200');
  }
}

Recommendation: CSS container queries for backgrounds, slimmage for <img> elements. Browser support: Chrome 105+, Firefox 110+, Safari 16+ (>95% global coverage).

How It Works

Three steps, zero configuration beyond the template URL.

API Reference

Everything slimmage exports, at a glance.