The basics
Section titled “The basics”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.
One bundle, every size
Section titled “One bundle, every size”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
<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 and click
Section titled “Hover and click”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.
Playing from script
Section titled “Playing from script”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>Inline in text
Section titled “Inline in text”Like an emoji
Sprites sit in a line of text
<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>Loading, errors and fallbacks
Section titled “Loading, errors and fallbacks”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
<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>Styling
Section titled “Styling”::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.