Bots

Small animated characters for the web. Five bots, five activity states, transparent backgrounds, and no runtime dependencies.

Try the playground.

Install

npm install @manxz/bots

Use

Add a container to your page:

<div id="bot"></div>

Then run this in your browser application's JavaScript, after the container exists:

import { createBot } from '@manxz/bots/wooden-block';

const bot = createBot('#bot', { state: 'idle', size: 120 });

// Update the character as your application works.
bot.setState('thinking');
bot.setState('listening');

Use a browser bundler that supports new URL('./asset', import.meta.url), such as Vite. The package includes its media; your build serves those files alongside your app. There is no external asset service or separate CSS to install. A bare npm import belongs in your application's bundled JavaScript, not a plain HTML script without a bundler.

Characters

Choose one import. Each entry references only that character's media.

| Character | Import | | --- | --- | | Wooden block | @manxz/bots/wooden-block | | Crystal orb | @manxz/bots/crystal-orb | | Mossbot | @manxz/bots/moss-bot | | Retro bot | @manxz/bots/retro-bot | | Ghost bot | @manxz/bots/ghost-bot |

The root import, @manxz/bots, also uses Wooden block.

States

fly-in and spin play once, then return to idle. listening, thinking, and idle loop. Calling setState again restarts the requested animation; a later request replaces any pending earlier request.

The player keeps the previous image visible until the next video has a decoded frame. By default, it loads the initial animation first, then warms the other four sequentially. The first visit still needs to download media; preloading makes later switches quicker.

Options

const bot = createBot(document.querySelector('#bot'), {
  state: 'idle',
  size: 120,
  autoplay: true,
  preload: true,
  label: 'Assistant', // Optional; decorative when omitted.
});

size is the square canvas width and height in CSS pixels, including the original animation's transparent padding. The supplied videos are 480 × 480 at 30 fps. preload: false loads animations on demand instead of warming the remaining states. With autoplay: false, call resume() to start playback; state changes made while paused update the requested state without playing it.

Lifecycle

await bot.ready; // Initial media is prepared; it may be paused/offscreen.
await bot.setState('thinking'); // true after a frame is shown; false if interrupted.
bot.pause();
bot.resume();
bot.destroy(); // Call when your component unmounts.

ready and setState() reject on media/network errors, so applications can catch these to show their own fallback. A state change interrupted by another request, pause, a hidden page, or destruction resolves false. state reports the requested state; element is the owned wrapper appended to your container. Existing container content is preserved.

Playback pauses while the page is hidden or the character is offscreen. People who prefer reduced motion see a static poster initially; an explicit state change can play an animation. Imports are safe on the server, but call createBot in the browser (for example in a component's mount effect), and call destroy during cleanup.

Browser support

The package ships both VP9 WebM and HEVC MOV with transparency. The player prefers supported HEVC and downloads one format per clip unless decoding fails, in which case it tries the fallback. It uses muted inline video and retains its poster if initial playback cannot begin. When using a Content Security Policy, allow your asset origin in connect-src and img-src, and blob: in media-src.

License

MIT © 2026 Oscar Manxz. The license applies to both the player code and all included bot animations and images. Personal and commercial use, modification, and redistribution are allowed with the copyright and license notice retained.