Skip to content

One tag

<script type="module" src="pixel-sprite.js"></script>
<pixel-sprite src="pip.bundle.json" anim="idle" size="128" alt="Pip"></pixel-sprite>

anim picks the animation (the first one by default), size is the height in CSS pixels, and alt is read by screen readers (alt="" makes it decorative). The box is reserved before the bundle loads, so the page does not jump.

Each bundle holds 16, 32 and 64 px renders drawn at different levels of detail. The element picks the one that fits, like srcset, and scales it by whole device pixels, so a sprite pixel is always an exact block of screen pixels.

Sizes pick detail levels

size 24 → 16 px icon
size 64 → 32 px sprite
size 128 → 64 px portrait
res 16 forced: chunky
<figure><pixel-sprite src="fox.bundle.json" anim="walk" size="24"></pixel-sprite><figcaption>size 24 → 16 px icon</figcaption></figure>
<figure><pixel-sprite src="fox.bundle.json" anim="walk" size="64"></pixel-sprite><figcaption>size 64 → 32 px sprite</figcaption></figure>
<figure><pixel-sprite src="fox.bundle.json" anim="walk" size="128"></pixel-sprite><figcaption>size 128 → 64 px portrait</figcaption></figure>
<figure><pixel-sprite src="fox.bundle.json" anim="walk" size="128" res="16"></pixel-sprite><figcaption>res 16 forced: chunky</figcaption></figure>

hover-anim and click-anim

<pixel-sprite src="pip.bundle.json" anim="idle" size="128"
hover-anim="walk" click-anim="wave" alt="Pip: hover to walk, click to wave"></pixel-sprite>

Hover animations are for mouse and pen. On a phone, a tap plays the click animation, or the hover animation once. If the bundle carries a state machine, its own interactions take over.

play(), pause(), flip

<pixel-sprite id="api-pip" src="pip.bundle.json" anim="idle" size="128"></pixel-sprite>
<div class="controls">
<button id="api-walk">play('walk')</button>
<button id="api-wave">play('wave', { once: true })</button>
<button id="api-flip">toggle flip</button>
<button id="api-pause">pause / resume</button>
<span class="readout" id="api-out"></span>
</div>
<script type="module">
const pip = document.getElementById('api-pip');
const out = document.getElementById('api-out');
document.getElementById('api-walk').onclick = () => pip.play('walk');
document.getElementById('api-wave').onclick = () => pip.play('wave', { once: true });
document.getElementById('api-flip').onclick = () => pip.toggleAttribute('flip');
document.getElementById('api-pause').onclick = () => (pip.hasAttribute('paused') ? pip.resume() : pip.pause());
pip.addEventListener('pixel-end', (e) => (out.textContent = `finished ${e.detail.anim}, back to ${pip.currentAnim}`));
</script>

Like an emoji

Sprites sit in a line of text using the 16 px icon render.

<p style="margin:0;font-size:18px">Sprites sit in a line of text
<pixel-sprite src="slime.bundle.json" anim="idle" size="24" alt="" style="vertical-align:-6px"></pixel-sprite>
using the 16 px icon render.</p>

Children of the element show until the sprite is ready, and again if it fails: a poster image works even without JavaScript. The status attribute (loading, ready, error) is there for CSS.

A broken link falls back to its poster

Pip (poster) loading…
<pixel-sprite id="fb" src="missing.bundle.json" size="96">
<img src="pip.poster.png" alt="Pip (poster)">
</pixel-sprite>
<span class="readout" id="fb-out">loading…</span>
<script type="module">
const el = document.getElementById('fb'), out = document.getElementById('fb-out');
const report = () => (out.textContent = `status="${el.status}": the poster shows instead`);
el.addEventListener('pixel-error', report);
if (el.status === 'error') report(); // it may have failed before this script ran
</script>

::part(canvas) and the status attribute

<style>
.halo::part(canvas) { filter: drop-shadow(0 6px 0 #0002); }
pixel-sprite[status=loading] { opacity: 0.4; }
</style>
<pixel-sprite class="halo" src="robot.bundle.json" anim="walk" size="128" alt="Bolt"></pixel-sprite>

Size sprites with size, not CSS width and height: the element sizes itself so pixels stay even.

Pixel Studio

Agents describe characters; the engine draws them as pixel art at every level of detail; websites play them with one tag.

© 2026 Pixel Studio · v0.2.0-alpha.2 · Released under the MIT licence.