Image generation
A loader for image cards: a living mosaic that resolves into the picture once it is ready.
Each card reveals an image from a shared pool every few seconds, then returns to generating.
Playground
Generating
<script>
import { ImageGeneration } from 'runeglow/img-fx';
let card; // the component, for its reveal functions
</script>
<ImageGeneration
bind:this={card}
preset="pixels-organic"
theme="dark"
images={['/images/a.jpg', '/images/b.jpg', '/images/c.jpg']}
>
<div style="width: 280px; height: 280px; border-radius: 20px;"></div>
</ImageGeneration>
<button onclick={() => (card.isImageActive() ? card.triggerHide() : card.triggerReveal({ hold: 'manual' }))}>
Reveal or hide
</button>
<button onclick={() => card.triggerRegenerate({ durationMs: 3000 })}>Regenerate</button>Install
pnpm add runeglow three Or copy just this library’s source into your project, with the shadcn-svelte CLI:
npx shadcn-svelte@latest add https://runeglow.dev/r/img-fx.json import { ImageGeneration } from 'runeglow/img-fx';This one needs three alongside the package. The other libraries don’t.
Usage
Wrap the card. The wrapper sizes itself to it and reads its corner radius. With autoReveal it shows an image from the pool on a loop.
<script>
import { ImageGeneration } from 'runeglow/img-fx';
</script>
<ImageGeneration preset="pixels-organic" images={['/img/a.jpg', '/img/b.jpg']} autoReveal>
<div class="card" style="width: 320px; height: 320px; border-radius: 20px;"></div>
</ImageGeneration>For a real generation flow, bind the component and call its functions: reveal when the image arrives, and regenerate to break it up and resolve the next.
<script>
import { ImageGeneration } from 'runeglow/img-fx';
let card; // the component
let { src, loading } = $props();
// Show the effect while the image is being made, then reveal it.
$effect(() => {
if (!loading && src) card?.triggerReveal({ hold: 'manual' });
});
</script>
<ImageGeneration bind:this={card} images={src}>
<div class="card"></div>
</ImageGeneration>
<button onclick={() => card.triggerRegenerate({ durationMs: 3000 })}>Regenerate</button>Props
Prop Type Default Description
preset 'pixels-organic' | 'pixels-mechanic' | 'sweep-gradient' 'pixels-organic' A flowing mosaic, a mechanical one, or a gradient sweeping corner to corner with cells flickering along it.images string | string[] – The pool of image URLs a reveal picks from. Same-origin, or served with CORS headers.autoReveal boolean false Reveals an image from the pool on a loop.revealDelayRange [number, number] [2, 4] Seconds between auto reveals, picked at random in this range.revealInitialDelay number | [number, number] – Seconds before the first auto reveal. Use it to stagger several cards.revealHoldMs number | [number, number] 2000 How long an auto-revealed image stays.revealFadeOutMs number 300 The cross-fade back to the effect.theme 'auto' | 'dark' | 'light' 'auto' auto reads data-theme or a dark/light class on <html>, then the system setting.strength number 1 Intensity, 0 to 2.speed number 1 Multiplier on the animation clock.pixelScale number 1 Size of the mosaic’s cells.cardBg string per preset The card surface the effect sits on and reasons against.colors (string | null)[] – Seven palette slots. null keeps the preset’s colour for that slot.borderRadius number auto Corner radius in px. Omit it to read the wrapped element’s.paused boolean false Freezes the effect and the reveal schedule.onCycle (event) => void – Called on each phase change: idle, reveal, visible, hide.excludeSrcs () => string[] | Set<string> – Images to avoid on the next pick, so cards sharing a pool don’t show the same one.fragmentShader string – A replacement fragment shader. It applies page-wide while set.ref HTMLDivElement | null – The wrapper element. Bindable with bind:ref....rest HTMLAttributes<HTMLDivElement> – class, style and other attributes are forwarded to the wrapper.Functions
Bind the component with bind:this and call these on it.
Function Type Default Description
triggerReveal(opts?) { hold?: 'auto' | 'manual' } – Reveals an image now. With hold: manual it stays until triggerHide().triggerHide() – Fades the revealed image back to the effect.triggerRegenerate(opts?) { durationMs?, tintFromImage?, autoReveal? } – Breaks the revealed image into cells, churns, and resolves the next image from the pool.isImageActive() () => boolean – Whether an image is showing over the effect.Notes
- One WebGL context is shared by every card on the page, and cards pause while offscreen.
- The effect runs at 10 frames a second by default, which suits its slow drift.
setFrameRateraises it. - Cell size is in CSS pixels, so a larger card gets more cells, not bigger ones.
- Regenerate samples its colours from the image on screen. That needs same-origin images or CORS headers; without them it falls back to the preset’s palette.
- Regenerate always churns as a pixel mosaic. A gradient sweep card switches to one for the churn and back once the next image is shown.