# Putting a sprite on a page

> <pixel-sprite> is one dependency-free module. Point it at a bundle, give it a size, and it picks the right resolution, keeps pixels crisp on every screen, and plays.

import LiveExample from '../../../../components/LiveExample.astro';

## The basics

<LiveExample
  title="One tag"
  code={`<script type="module" src="../packages/runtime/src/pixel-sprite.js"></script>
<pixel-sprite src="../demo/assets/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

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.

<LiveExample
  title="Sizes pick detail levels"
  code={`<figure><pixel-sprite src="../demo/assets/fox.bundle.json" anim="walk" size="24"></pixel-sprite><figcaption>size 24 → 16 px icon</figcaption></figure>
<figure><pixel-sprite src="../demo/assets/fox.bundle.json" anim="walk" size="64"></pixel-sprite><figcaption>size 64 → 32 px sprite</figcaption></figure>
<figure><pixel-sprite src="../demo/assets/fox.bundle.json" anim="walk" size="128"></pixel-sprite><figcaption>size 128 → 64 px portrait</figcaption></figure>
<figure><pixel-sprite src="../demo/assets/fox.bundle.json" anim="walk" size="128" res="16"></pixel-sprite><figcaption>res 16 forced: chunky</figcaption></figure>`}
/>

## Hover and click

<LiveExample
  title="hover-anim and click-anim"
  code={`<pixel-sprite src="../demo/assets/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](/docs/guide/states/), its own interactions take over.

## Playing from script

<LiveExample
  title="play(), pause(), flip"
  code={`<pixel-sprite id="api-pip" src="../demo/assets/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

<LiveExample
  title="Like an emoji"
  code={`<p style="margin:0;font-size:18px">Sprites sit in a line of text
  <pixel-sprite src="../demo/assets/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

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.

<LiveExample
  title="A broken link falls back to its poster"
  code={`<pixel-sprite id="fb" src="missing.bundle.json" size="96">
  <img src="../demo/assets/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

<LiveExample
  title="::part(canvas) and the status attribute"
  code={`<style>
  .halo::part(canvas) { filter: drop-shadow(0 6px 0 #0002); }
  pixel-sprite[status=loading] { opacity: 0.4; }
</style>
<pixel-sprite class="halo" src="../demo/assets/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.
