Tiny Tells
Cast Customize In the Wild Install
Docs
Preview with
Core Play
v0.6.0

Tiny Tells Docs

Tiny Tells is one custom element, <tiny-tell>. It shows what your app is doing with a small animated character instead of a spinner. Pick one of six tells with the tell attribute and one of five states with state. Change the state and the tell springs into the new one.

Start

Get Started Build with AI

Use

Tells States Accessibility

Customize

Size Color Styling Play Bundle

Integrate

Frameworks and Editors Agent Status Testing Your App Before It Loads

Reference

API Browser Support How It Works Project

Just for Fun

Funsies

Start

Get Started

Three steps: load it, add a tell, change its state. Working with a coding assistant? Skip to Build with AI and let it do these for you.

1. Load It

Three ways to load it, all the same element. Pick the one that matches how you build. Flip on the play bundle and tells glance at the pointer, dance, and doze off.

Play Bundle npm CDN Self-Host

Using a bundler? Install the package and import it once, anywhere:

npm i tiny-tells
import 'tiny-tells';

The import registers the element as it runs. Types ship in the package. Need the class itself? Import it by name with import { TinyTell } from 'tiny-tells'.

No build step? Add the script tag:

<script type="module" src="https://cdn.jsdelivr.net/npm/tiny-tells@0.6.0/dist/tiny-tells.min.js"></script>
Keep the version in the URL until 1.0. A breaking change can’t reach your site until you choose to update.

Copy dist/tiny-tells.min.js from the package into your site and load it like any other module. Want to read or debug it? dist/tiny-tells.js is the same code, unminified.

<script type="module" src="/js/tiny-tells.min.js"></script>

2. Add a Tell

Put it next to the words it describes. label="" stops screen readers from saying the state twice. role="status" announces the words when they change. More on that.

Syncing 3 files…

<p>
  <tiny-tell tell="dekatron" state="working" label=""></tiny-tell>
  <span role="status">Syncing 3 files…</span>
</p>

3. Change Its State

Set state from your code, and change the words at the same time.

Syncing 3 files…

Run It
const tell = document.querySelector('tiny-tell');
const words = document.querySelector('[role="status"]');

tell.state = 'done';
words.textContent = 'Synced 3 files.';

Build with AI

Claude Code, Codex, Cursor, Copilot: any assistant that can read a URL can add Tiny Tells for you. Point it at llms.txt, a plain-text copy of these docs written for assistants. It has the install, the attributes, and the rules an assistant gets wrong without them (words beside every tell, warning only when a person has to act).

Paste-In Prompt

For a one-off. Paste it into the chat:

Add Tiny Tells to this project. Read https://tinytells.dev/llms.txt first, and follow its rules for pairing each tell with status text. Ask me where it should go before adding any.

Project Rules

For every session after this one. Add this to the instructions file your assistant reads on its own. Codex, Cursor, and Copilot read AGENTS.md. Claude Code reads CLAUDE.md, which can pull in AGENTS.md with a line that says @AGENTS.md.

## Tiny Tells

- Before adding or changing a `<tiny-tell>`, read https://tinytells.dev/llms.txt and follow its Rules.

Agent Skill

For assistants that load skills. Install it in your project once:

npx skills add talbs/tiny-tells

It’s the same text as llms.txt, so the rules and API are there without fetching anything. Run npx skills update after you upgrade Tiny Tells.

Manifest and Types

Installed from npm, the package carries its own description. custom-elements.json lists every attribute, event, and CSS hook. The TypeScript types flag tell.state = 'workin' before it ships. See Frameworks and Editors.

Use

Tells

Pick one with tell. They all say the same five things. What differs is the personality, so pick the one that fits your product. A typo logs a warning and gets you Drones.

Tell tell Who It Is
dronesA squad of four drones running drills, keen and prone to pile-ups. Their shadows are the floor.
flipdotA 5×5 flip-disc board, like the ones on old bus signs. Every disc clacks over and wobbles before it settles. All business.
eyesTwo eyes on a dark visor, and the most human of the six. The eyes dart first, the head catches up, and every mood morphs into the next.
blotA drop of cartoon liquid that reaches, drips, splats, and pulls itself back together, with real gravity and generous squash and stretch.
dekatronA 1950s counting tube. One glow hops around a ring of ten. Precise and steady, right up until it jams.
lensOne calm, watchful eye behind smoky glass in a metal bezel. The iris does all the talking.

States

Set one with state. A typo logs a warning and gets you working.

Tell state Means Use It
workingBusy and making progress.For the whole wait, from the first step to the last.
doneFinished, and it worked.Once the work is really finished, not just sent.
errorFailed.Always with words beside it that say what broke.
warningStuck until a person acts.When someone has to act on an approval, a conflict, or a sign-in, and nothing is broken.
idleNothing in progress.For anything ready, queued, or up to date, when nobody is waiting on it.

People mix up warning and idle. Warning means someone has to act. Idle means nobody’s waiting. Whatever the state, put words beside it. When the change matters, put them in a role="status" region so screen readers announce it:

Waiting for your approval to deploy.

Deploy queued.

<p>
  <tiny-tell state="warning" label=""></tiny-tell>
  <span role="status">Waiting for your approval to deploy.</span>
</p>
<p>
  <tiny-tell state="idle" label=""></tiny-tell>
  <span role="status">Deploy queued.</span>
</p>

In a list or table, each row’s tell keeps its state name. A region per row announces each row as it changes, so put the summary in one region:

  • report.pdf
  • photo.jpg

1 of 2 uploaded.

<ul>
  <li><tiny-tell state="done"></tiny-tell> report.pdf</li>
  <li><tiny-tell state="working"></tiny-tell> photo.jpg</li>
</ul>
<p role="status">1 of 2 uploaded.</p>

Accessibility

A tell is a hint, never the message. The words carry the status. The tell is what you notice at a glance. Tiny Tells handles motion, contrast, forced colors, and flashing. The one thing it can’t know is what’s actually happening, so that part is yours.

Your Part

  1. Put words beside it, not inside the tag. A tell is never the only signal. Text inside the tag hides once the tell loads. See it.
  2. Hide its name when the words already say it with label="". It works like alt="" on a decorative image. Try it.
  3. If the status changes while someone’s on the page, put the words in a role="status" region so screen readers announce it. Keep the region in the page from the start, and hide what’s inside it, not the region. A list gets one region for the summary. Run it.
  4. If you change the colors, keep 3:1 against the surface (WCAG 1.4.11). Check yours.
  5. If it moves for more than five seconds, give people a pause button (WCAG 2.2.2). Copy one.
  6. If you load play, put noplay on busy lists, so only the tells you want playing do. See how.

Handled for You

  • A name. Shows up as an image named by its state, or by the label attribute.
  • Reduced motion. Holds one still pose per state, and play turns off.
  • Forced colors. Draws in the system text color in Windows High Contrast mode.
  • Contrast. Meets 3:1 with the built-in palette.
  • Flashing. Never more than three flashes a second (WCAG 2.3.1).
  • Off-screen. Stops animating while it’s scrolled out of view.
  • Pausing. Holds its current frame with the paused attribute.

Labels

Screen readers read a tell as an image named after its state, like “Working”. Set label to be more specific. Set label="" to hide the tell when the words beside it already say the state. Forget it beside a live region, and the console reminds you.

Use label, not aria-label. aria-label and aria-labelledby work too, and override label. Firefox ignores them before version 119, though, so label is the safe one.
Tell Attribute Screen Readers Hear
no label “Working”, an image
label="Uploading photos" “Uploading photos”, an image
label="" Nothing. The tell is hidden.
no label, inside a role="status" region “Working”, an image, then the words, on every change
<tiny-tell></tiny-tell>
<tiny-tell label="Uploading photos"></tiny-tell>
<tiny-tell label=""></tiny-tell>
<p role="status"><tiny-tell></tiny-tell> Saving…</p>

Pausing

paused freezes a tell on its current frame. Remove it and the tell rejoins the shared beat.

paused

Anything that moves for more than five seconds needs a way to stop it (WCAG 2.2.2). One button covers every tell on the page:

Pause Animations
<button type="button" id="pause-tells">Pause animations</button>

<script>
  let isPaused = false;
  document.getElementById('pause-tells').addEventListener('click', event => {
    isPaused = !isPaused;
    event.currentTarget.textContent = isPaused ? 'Resume animations' : 'Pause animations';
    document.querySelectorAll('tiny-tell').forEach(tell => (tell.paused = isPaused));
  });
</script>

Customize

Size

Usually you don’t set one.

Follow the Text

A tell sizes itself to the text it sits in: about 1.4 times the font size, never under 20px or over 48px. Under the hood that’s clamp(20px, 1.43em, 48px).

Syncing your files

Syncing your files

Syncing your files

<p>Syncing your files <tiny-tell></tiny-tell></p>

Pin a Size

Set --tell-size when a tell should hold one size whatever the text does (a toolbar, a table column). It inherits, so set it on the tell or any container above it:

Draft 1,204 words Saved
.toolbar { --tell-size: 1.5rem; }

Pick a Value

Any CSS length works. They’re drawn for 20 to 48px, though, and it shows outside that range:

tiny-tell { --tell-size: 2rem; }

Color

Five custom properties, one per state. Set them on :root or any container, with any CSS color, light-dark() included. Skip one and it keeps the built-in color. The play bundle adds a sixth for its dance.

The rule: 3:1 against the surface behind the tell. The built-in palette clears it in light and dark. Pick a palette below and the chips check it for you.

The CSS for the palette you picked:

Use Your Design System’s Colors

Point the tokens at your system’s, and declare them on the same selectors your system uses to switch theme. The names below are stand-ins:

data-theme="light"

data-theme="dark"

:root,
[data-theme] {
  --tell-color-working: var(--color-accent);
  --tell-color-done: var(--color-success);
  --tell-color-error: var(--color-danger);
  --tell-color-warning: var(--color-warning);
  --tell-color-idle: var(--color-neutral);
}
Set the tokens where the theme switches. A var() resolves where it’s declared. Set the tokens only on :root and a dark region still gets the light values.

Match the Text Color

color="current" drops the state colors and draws in the text color around the tell, even inside another component’s slot. Use it on a filled button or a badge, where green on brand blue looks like a mistake.

Syncing

Default: state colors

Syncing

color="current": matches the text

<tiny-tell></tiny-tell>
<tiny-tell color="current"></tiny-tell>

Match Light or Dark

Each tell has a light drawing and a dark one, and scheme picks. auto (the default) reads the color-scheme around it. Use invert for a tell on a filled badge or button.

In a light region

auto
light
dark
invert

In a dark region

auto
light
dark
invert
<tiny-tell scheme="auto"></tiny-tell>
<tiny-tell scheme="light"></tiny-tell>
<tiny-tell scheme="dark"></tiny-tell>
<tiny-tell scheme="invert"></tiny-tell>

Styling

Size and color cover most of it. Past that, you get two hooks. The drawing itself is one canvas, so there’s nothing inside to restyle.

  • The canvas: ::part(tell). Opacity, filters, transforms.
  • The state: :state(working), :state(done), and so on. Style the things around the tell by what it’s showing. These need newer browsers. The second line below is the fallback for older ones.

Upload failed.

Uploading…

tiny-tell:state(error) + .message { color: var(--danger); }
tiny-tell[state="error"] + .message { color: var(--danger); }

Matching working by attribute? Add tiny-tell:not([state]) too. A tell with no state is working.

Default: full strength

.muted: steps back

.muted tiny-tell::part(tell) { opacity: 0.6; }

Play Bundle

The same element and API, with three extras for the person at the screen. It costs under 2.5 KB more, gzipped. The core bundle reports status and that’s it. Reach for play when the tell is part of the product’s personality.

Extra Happens When
Glance a mouse pointer comes near
Dance someone taps it five times quickly, or you call tell.dance()
Doze an idle tell is left alone for 30 seconds. It wakes when the pointer comes back. Never on touch screens.
  • Skip it with noplay. The tell keeps its state animation, with no glance, tap dance, or doze. Use it where many tells sit together, like a dense table. tell.dance() still works.
  • Reduced motion and paused both switch play off.
  • Recolor the dance with --tell-color-dance (sky blue by default). Any CSS color works, light-dark() included. It wins over color="current", so a tell that matches its text can still dance in color.

Core: keeps to itself

Play: looks your way

Move your pointer between them, or tap the play one five times. Dance

Load it in place of the core bundle:

npm CDN Self-Host
import 'tiny-tells/play';
<script type="module" src="https://cdn.jsdelivr.net/npm/tiny-tells@0.6.0/dist/tiny-tells-play.min.js"></script>
<script type="module" src="/js/tiny-tells-play.min.js"></script>
From a CDN, load one bundle, not both. Each CDN file carries the whole element. Load both and the first one wins, with a console warning. From npm, importing both is safe since they share one element, but then every tell on the page plays.

Integrate

Frameworks and Editors

It’s a plain custom element. Anything that renders HTML renders a tell, and Svelte, Lit, and plain HTML need nothing else. React, Vue, and Angular each want one small setup step, below.

Types and Editors

  • TypeScript: dist/tiny-tells.d.ts types the element and exports TinyTell, TinyTellAttributes, TellName, TellState, TellColor, and TellScheme. The play bundle’s types add TellDanceEvent, TellAfterDanceEvent, and the dance events on addEventListener.
  • Custom Elements Manifest: dist/custom-elements.json describes the element to anything that reads the format: Storybook, docs generators, coding assistants. The package’s customElements field points to it, so most tools find it on their own.
  • VS Code: add the custom data file to html.customData for attribute autocomplete in HTML files. On the CDN or self-hosting, download the same file into your project and point the setting at it.
{
  "html.customData": ["./node_modules/tiny-tells/dist/vscode.html-custom-data.json"]
}

React

React 19 works out of the box.

In React 18, leave paused off instead of setting it to false. React 18 writes every value as an attribute string, so paused={false} becomes paused="false", and that still pauses.

With TypeScript, drop this in any .d.ts file so <tiny-tell> type-checks in JSX. It works with React 18 and 19 types:

import type { DetailedHTMLProps, HTMLAttributes } from 'react';
import type { TinyTell, TinyTellAttributes } from 'tiny-tells';

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'tiny-tell': DetailedHTMLProps<HTMLAttributes<TinyTell>, TinyTell> & TinyTellAttributes;
    }
  }
}

Vue and Angular

Both need to be told <tiny-tell> isn’t one of their components. In Vue, pass this to the Vue plugin in vite.config.js:

vue({
  template: { compilerOptions: { isCustomElement: tag => tag === 'tiny-tell' } },
})

In Angular, add CUSTOM_ELEMENTS_SCHEMA to the component that uses it:

@Component({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})

Web Awesome

This site runs on Web Awesome, so the examples below are live. A tell goes in a slot like anything else. Give it color="current" and it takes the component’s text color, which is what keeps it readable on a loud button. For state colors, pick the Web Awesome preset under Use Your Design System’s Colors.

In a button’s start slot. Click it.

Save
<wa-button variant="brand">
  <tiny-tell slot="start" tell="eyes" state="idle" color="current" label=""></tiny-tell>
  Save
</wa-button>

On click: working while the save runs, then done.

const button = document.querySelector('wa-button');
const tell = button.querySelector('tiny-tell');
button.addEventListener('click', async () => {
  tell.state = 'working';
  await save();
  tell.state = 'done';
});

In a callout’s icon slot:

Two copies of this file changed. Pick the one to keep.
<wa-callout variant="warning">
  <tiny-tell slot="icon" tell="eyes" state="warning" color="current" label=""></tiny-tell>
  Two copies of this file changed. Pick the one to keep.
</wa-callout>

Inline in a tag:

Queued
<wa-tag>
  <tiny-tell tell="eyes" state="idle" color="current" label=""></tiny-tell>
  Queued
</wa-tag>

Agent Status

An agent run fits the five states. A spinner covers working. What it can’t show is warning: the run stopped and it’s waiting on a person. That’s the state that costs time when nobody notices it.

Map your SDK’s status to a state, set it on the tell, and put the words in a role="status" region. A chat reply counts as a run. A run someone stopped is your call (most apps go back to idle).

State The Run Is AI SDK LangGraph.js OpenAI Agents SDK Claude Agent SDK
working thinking or streaming status is submitted or streaming invoke() hasn’t returned run() hasn’t settled query() is still yielding
done finished status is ready after a reply returned with no __interrupt__ returned with no interruptions a result message with subtype success
error failed status is error invoke() threw run() threw any other result subtype, or it threw
warning waiting on a person a tool part in approval-requested __interrupt__ in the result result.interruptions has entries canUseTool hasn’t returned
idle not started status is ready before any reply nothing started yet nothing started yet nothing started yet

Set State and Words Together

The LangGraph, OpenAI, and Claude examples share this:

const tell = document.querySelector('tiny-tell');
const words = document.querySelector('[role="status"]');
const TEXT = { working: 'Thinking…', done: 'Done', error: 'Something broke', warning: 'Needs your OK', idle: 'Ready' };

const show = state => {
  tell.state = state;
  words.textContent = TEXT[state];
};
Call show() in the page, not next to the SDK. Those SDKs usually run on a server. Call it wherever the page hears about the run: a stream, a socket, or a poll.

AI SDK

  • ready means two things: nothing started yet, or a reply (or stop()) just finished. This example calls it done once there’s a reply on the page.
  • Approvals go back on their own with sendAutomaticallyWhen, so done means the tool really ran.
import { useChat } from '@ai-sdk/react';
import { lastAssistantMessageIsCompleteWithApprovalResponses } from 'ai';

const TEXT = { working: 'Thinking…', done: 'Done', error: 'Something broke', warning: 'Needs your OK', idle: 'Ready' };

const stateOf = (status, messages) => {
  const parts = messages.at(-1)?.parts ?? [];
  if (parts.some(p => p.state === 'approval-requested' && !p.approval?.isAutomatic)) return 'warning';
  if (status === 'error') return 'error';
  if (status !== 'ready') return 'working';
  return messages.length ? 'done' : 'idle';
};

function RunStatus() {
  const { status, messages } = useChat({
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
  });
  const state = stateOf(status, messages);
  return (
    <p>
      <tiny-tell state={state} label="" /> <span role="status">{TEXT[state]}</span>
    </p>
  );
}
Skip automatic approvals. They pass through approval-requested too, with approval.isAutomatic set. Count them and the tell shows warning when nobody needs to act.

LangGraph.js

A paused graph comes back with __interrupt__ set. Answer it with new Command({ resume }) on the same thread and it’s working again:

show('working');
try {
  const result = await graph.invoke(input, config);
  show(result.__interrupt__?.length ? 'warning' : 'done');
} catch {
  show('error');
}

OpenAI Agents SDK

A run that needs approval stops and fills result.interruptions. Approve or reject each one on result.state, then run again:

import { run } from '@openai/agents';

show('working');
try {
  const result = await run(agent, input);
  show(result.interruptions.length ? 'warning' : 'done');
} catch {
  show('error');
}

Claude Agent SDK

The run doesn’t stop for approval. It waits inside canUseTool until you answer, so the tell switches to warning there and back when the person decides. askUser stands in for your own approval UI:

import { query } from '@anthropic-ai/claude-agent-sdk';

const canUseTool = async (toolName, input) => {
  show('warning');
  const isAllowed = await askUser(toolName, input);
  show('working');
  return isAllowed ? { behavior: 'allow', updatedInput: input } : { behavior: 'deny', message: 'Declined' };
};

show('working');
try {
  for await (const message of query({ prompt, options: { canUseTool } })) {
    if (message.type === 'result') show(message.subtype === 'success' ? 'done' : 'error');
  }
} catch {
  show('error');
}

Testing Your App

  • Test DOMs (jsdom, happy-dom): tells go inert. Attributes and properties work, nothing draws, and nothing logs, so Jest and Vitest output stays clean.
  • Screenshot tests (Playwright, Puppeteer): emulate reduced motion. Every state holds one fixed pose, so screenshots match from run to run.
await page.emulateMedia({ reducedMotion: 'reduce' });

Before It Loads

Until the script runs, <tiny-tell> is an empty inline element. Then the tell appears and shoves the words beside it over. A late tell is fine (the words already say the status). The layout shift isn’t, and it counts against your Cumulative Layout Shift.

Hold Its Space

Load reserve.css before the script. It gives every tell the box it’ll have once it loads, so nothing moves:

npm CDN Self-Host
import 'tiny-tells/reserve.css';
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tiny-tells@0.6.0/dist/reserve.css">
<link rel="stylesheet" href="/css/reserve.css">

Show a Stand-In

If the script might never arrive (a blocked CDN, JavaScript off), draw something in the reserved space. The state attribute is already on the tag, so plain CSS can follow it:

Without the script • working ✓ done ✕ error ! warning
tiny-tell:not(:defined) { display: inline-grid; place-items: center; }
tiny-tell:not(:defined)::before { content: "•"; }
tiny-tell:not(:defined)[state="done"]::before { content: "✓"; }
tiny-tell:not(:defined)[state="error"]::before { content: "✕"; }
tiny-tell:not(:defined)[state="warning"]::before { content: "!"; }

Anything inside the tag shows until the element loads, then hides. With reserve.css it’s clipped to the tell’s box, so keep it to an icon or a short word.

To wait for it from script: await customElements.whenDefined('tiny-tell').

Reference

API

Attributes and Properties

Every attribute except noplay is also a property (tell.state = 'error'). Unknown values fall back to the default. An unknown tell or state logs a warning too.

Attribute Values Default
tellOne of the six tells
Which tell to draw. How to use it.
drones
stateOne of the five states
What the tell is reporting. Changing it hands off into the new state. How to use it.
working
colorstate, current
Where the color comes from. How to use it.
state
schemeauto, light, dark, invert
Light or dark drawing. How to use it.
auto
labeltext
Accessible name. Defaults to the state. Set it to an empty string when nearby text already says the state. How to use it.
—
pausedboolean
Holds the current frame. How to use it.
—
noplayPlay Onlyboolean
Turns play off for this tell. It won’t glance at the pointer, dance to five taps, or doze, but it still animates its state. Set it in markup or with toggleAttribute('noplay'). How to use it.
—

CSS Custom Properties

All of them inherit. Size and Color show them in use.

Property Default Does
--tell-sizeclamp(20px, 1.43em, 48px)Width and height. Tuned for 20 to 48px.
--tell-color-working—Working color. Any CSS color, including light-dark().
--tell-color-done—Done color. Any CSS color, including light-dark().
--tell-color-error—Error color. Any CSS color, including light-dark().
--tell-color-warning—Warning color. Any CSS color, including light-dark().
--tell-color-idle—Idle color. Any CSS color, including light-dark().
--tell-color-dancePlay Only—Dance color. Any CSS color, including light-dark(). Unlike the state colors, it applies even with color="current".

CSS Parts

Part Is
tellThe canvas.

Custom States

These need newer browsers than the rest. Styling has the fallback.

Selector Matches When the Tell Is
:state(working)Busy and making progress.
:state(done)Finished, and it worked.
:state(error)Failed.
:state(warning)Stuck until a person acts.
:state(idle)Nothing in progress.

Events

The core fires no events. It only shows the state you set, so there’s nothing new to report. The play bundle fires two around a dance (dozing fires none, since the state stays idle). Both bubble and cross shadow roots, so listen on the tell or anywhere above it.

Event Cancelable Fires
tell-danceYesFires before a tell dances. Call preventDefault() to keep it still.
tell-after-danceNoFires when a dance ends, or when a state change, a switch to another tell, or removing it cuts it short. A removed tell is off the page, so only listeners on the tell itself hear that one.
  • Length: a dance lasts two loops, about 6.4 seconds.
  • No tell-dance while a tell is paused, under reduced motion, or mid-dance.
  • Pausing freezes the frame but not the dance’s clock. If the time’s up when you unpause, tell-after-dance fires right then.
  • A canceled dance never started, so it gets no tell-after-dance.

Tap it five times, or press Dance.

Hold Still Dance
const tell = document.querySelector('tiny-tell');
const words = document.querySelector('[role="status"]');
const holdStill = document.querySelector('#hold-still');

tell.addEventListener('tell-dance', event => {
  if (holdStill.checked) event.preventDefault();
  words.textContent = holdStill.checked ? 'Asked to dance, and held still.' : 'Dancing…';
});

tell.addEventListener('tell-after-dance', () => {
  words.textContent = `Back to ${tell.state}.`;
});

Static Properties

Property Type Does
TinyTell.versionRead-OnlystringThe version that’s loaded.
TinyTell.timeScalenumberExperimental. Multiplies every tell’s clock: 1 is normal, 0.5 is half speed, 2 is double. 0, a negative, or anything that isn’t a finite number stops them.

Methods

Method Returns Does
dance()Play OnlybooleanDances once, same as five quick taps. Works on a noplay tell too. Returns false when it can’t: paused, reduced motion, already dancing, off the page, or tell-dance canceled.
No custom tells yet. The internals are still moving, so there’s no API for adding your own.

Browser Support

These versions and later. That covers every browser in Baseline’s Widely available set.

  • Chrome 111
  • Firefox 113
  • Safari 16.4

Two features need newer browsers:

Feature Chrome Firefox Safari In Older Browsers
:state() selectors 125 126 17.4 Match the state attribute instead.
scheme="auto" 123 120 17.5 Follows the system’s light or dark setting, not the container’s color-scheme.

How It Works

A tell is animated like a character, not swapped like an icon. All six follow the same few rules, and the demos below are running them live.

One Beat, One Clock

Everything runs on a 0.8s beat. A loop is four beats (idle takes six). Every tell on the page shares one clock, so a row of them stays in time, and each lands its biggest move on the beat.

  1. 1
  2. 2
  3. 3
  4. 4
All six tells, one clock. The bar steps once a beat. Start Over

Handoffs

Change the state and the tell doesn’t cut to the new loop. It springs from wherever it is, keeping its momentum, so even a switch halfway through a move looks intended. A sprite sheet or a GIF would have to cut.

Cut: starts the new loop cold

Handoff: springs from where it is

Switch mid-move and watch the right one.

Small on Purpose

Tells drop detail as they shrink, so each still reads at 20px. At 32px and under, Eyes loses its glow and Dekatron’s ten cathodes merge into one ring.

At 32px and under, four of the six switch to a simpler drawing. Flipdot and Lens keep theirs.

Drawing

Each tell is one canvas at your screen’s full resolution, and off-screen tells stop drawing. On a recent laptop, 100 on screen run above 60 fps. On a CPU four times slower, they run at about 40. Try yours:

Held still for now. Run All 100

Tested

Every change is tested in Chromium, Firefox, and WebKit, and every tell has to pass the same checks:

  • stay inside its live area
  • loop without a seam
  • never flash more than three times a second
  • draw in system colors under forced colors

Project

License

MIT. Use it in anything, commercial work included. The license file has the full text.

Versions

Pre-1.0. It’s tested, but names and defaults can still change, so pin a version. Fixes only go to the latest release. Every release is in the changelog, and TinyTell.version tells you which one you’ve got.

Contributing

Bugs go in an issue: the browser, the tell, the state, what you saw. A screen recording helps a lot. For anything bigger, open an issue before the pull request so we agree on it first. New tells aren’t open yet, but fork away. Security problems go through GitHub’s private report, not a public issue. The rest is in CONTRIBUTING.md.

Stats

The site counts visits with Umami, plus which tell you pick, which install tab you open, and which palette you try. There are no cookies, and nothing in the totals identifies you. To leave yourself out, open ?stats=off once in each browser. ?stats=on puts you back.

Funsies

The tells are off the clock here. None of this teaches anything.

These need motion. Your system asks for reduced motion, so these stay still.

Dance Party

The whole cast dances, a sixth of a beat apart.
Start the Show

Tap a beat

Tap Tempo

Every tell on the page follows your beat while you tap, then settles back.
Tap

The Wave

Every state rolls down the row, stadium style.
Do the Wave

Audience

They watch you and get bored when you stop.

Tiny Tells Rev 0.6.0 MIT Made by @talbs with

GitHub npm Docs Issues