# Ally tracker
> A game HUD’s column of companions: glowing creatures with charges, turning red and refilling while they recharge.
The column a game keeps at the edge of the screen for the allies whose powers the player can call on. Each creature glows in its own colour with its charges at its top right; a call squashes it, bursts it with a ring and pops the count, and the last charge drops it into red, dark and empty, filling from the bottom as it recharges until it flashes back. Click an ally, or press 1 to 4.
A React component by Bruno Delorence: https://brunodelorence.com/components/ally-tracker. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: Games · HUD.
## Anatomy
1. **Plate**: The column on a dark rounded plate, the same on light and dark stages, so the glows always read; one 3.75 em row per ally, in em of the count’s 24 px type, smaller on a narrow stage.
2. **Ally**: One row, holding a button named with its charges or its recharge; click, Enter, Space or its number key calls it.
3. **Ready creature**: The creature in its own colour: a thick stroke of the silhouette under a pale body, sharp at any pixel ratio, over a blurred copy that makes its halo.
4. **Charges**: “×N” in italic at the creature’s top right, white in its colour’s glow; it pops on every change.
5. **Spent creature**: At 0 charges: a red rim, a dark red body, no count, and a red halo that breathes while it recharges.
6. **Recharge fill**: A pale red copy of the creature, clipped from the top so it rises over the silhouette (not the box) as `recharge` goes from 0 to 1.
7. **Hint**: How to call an ally, on a neutral chip under the column with the keys as keycaps; left out with `bare`.
## When to use
- A game HUD with a few companions or summons whose powers the player can call on a limited number of times, then must wait for.
- Abilities with charges and a cooldown, where the player has to read at a glance which are ready, how many uses are left and how far a spent one has come back.
- A column at the screen’s edge that stays out of the way of play: a dark plate and no labels until hover or focus, a number key per ally.
- Calls the game makes as well as the player: given `allies`, it animates whatever the game does to the charges.
## When not to use
- A single ability on a cooldown. Use a round cooldown timer or a radial fill on its button.
- An ability bar of eight or more actions bound to keys. Use a hotbar with key hints along the bottom.
- Showing an ally’s health or status. Use a portrait with a health bar; this shows only charges and recharge.
- Buffs and effects that run out on their own. Use an effect timer with a countdown ring.
- Interfaces outside a game: a quota of credits or seats left. Use a meter with a count.
## Installation
Install it with the shadcn CLI, into components/ally-tracker of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/ally-tracker.json
```
Or copy all the source files below into one folder of your project. Either way it needs React 19 and a bundler with CSS Modules (Next.js, Vite).
It has a dark colour scheme. Its colours are CSS light-dark() pairs, kept inside @supports so that builds which rewrite light-dark() for older browsers leave them alone: it follows your page’s color-scheme (light unless the page sets one) or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
## Usage
```tsx
import { AllyTracker, type AllyTrackerItem } from './ally-tracker';
export function Companions({
allies,
onCall,
}: {
allies: AllyTrackerItem[];
onCall: (id: string) => void;
}) {
return ;
}
```
## States
- **All ready**: Every ally full, each glowing in its colour with its count. The charge states are drawn `bare`: the column on its plate.
- **Charges used**: The stag at ×1 of 3 and the fox at ×1 of 2: still ready, still in colour.
- **Just spent**: `charges: 0`, `recharge: 0`: the ray in red with no count and no fill yet.
- **Recharging**: The ray 60% back and the fox 25%: the pale red rises from the bottom of each.
- **All spent**: Every ally red, each at its own point of recharge; calls on them are refused with a shake.
- **On its stage**: Without `bare`: the column centred on the plain stage, with the hint chip under it, at the page’s colours.
- **Narrow stage**: At 360 px the container query draws the column at 18 px type instead of 24.
- **Light**: `colorScheme="light"`: a white stage. The plate keeps the HUD dark, as a game’s does.
- **Dark**: `colorScheme="dark"`, or a dark page: the same HUD on a near-black stage, its plate set off by a faint edge.
## How it works
- Each creature is an original SVG on a 48-unit grid, drawn in stacked layers of the same shapes: a thick stroke in the ally’s colour (a crisp rim with no seams where shapes overlap), the pale body with its engraving in the colour, and, while spent, a copy in the recharge colours. The halo is one more copy of the silhouette behind them, the only layer with a filter (two drop-shadows), so the creature itself stays sharp at any pixel ratio.
- A spent ally swaps its tokens to red: a dark body with bright red marks under a red rim. The recharge copy is cut by clip-path: inset() from the top down to the fill line, worked out on the silhouette’s own top and height (--top, --span) so the pale red rises over the creature and not over empty box. It eases between the clock’s steps with a 140 ms linear transition.
- The moments are keyframes on the creature, which is remounted for each one so it plays again: a call squashes to 0.86 (anticipation), bursts to 1.16 with a brighter, wider glow and a ring, and settles; the last charge flashes, then shakes and flickers into the red; a call on a spent ally is refused with a shake; recharged, it flashes white in its colour from 0.72 with a ring, and the full count pops in with an overshoot.
- The glow and the flash are registered custom properties (@property --ally-glow and --ally-flash) animated on the halo layer, its blur and its mix toward white, so a spent ally’s halo can breathe slowly on its own while it works.
- Moments are read from changes in charges, so a controlled tracker animates what the game does: fewer charges is a call (or a spend at 0), a return from 0 is a recharge.
- Uncontrolled, it keeps its own allies and recharges them on a clock advanced every 100 ms only while it is on screen in a visible tab and not paused. A demo plays a short run of calls while it is untouched; any input hands it to the reader for 8 s.
- The column sits centred on a plain stage, on its own dark plate (a gradient with a hairline edge and a soft lift), as a game keeps a shade behind its glows: it reads the same on the light and the dark stage, whose colours, with the hint chip’s, are light-dark() tokens. Sizes are in em of the count’s 24 px type (a 60 px creature on a 90 px row), so a container query draws the column smaller on narrow screens, and a bare column takes its size from --ally-size.
## API reference
- **allies** (`AllyTrackerItem[]`): The allies to show, controlled: each is { id, kind, label, charges, maxCharges, recharge? }, with kind one of drake, ray, fox or stag and recharge from 0 to 1 while charges is 0. The game owns the values; presses call onUse. Turns the demo off.
- **defaultAllies** (`AllyTrackerItem[]`, default `drake ×1, ray ×1, fox ×2, stag ×3`): Uncontrolled, the allies it starts with.
- **onUse** (`(id: string) => void`): Called with an ally’s id when the player calls on it while it has a charge.
- **onRecharged** (`(id: string) => void`): Uncontrolled, called with an ally’s id when it has recharged.
- **rechargeSeconds** (`number`, default `12`): Uncontrolled, how long a spent ally takes to recharge, in seconds.
- **paused** (`boolean`, default `false`): Stops recharging, as a game’s pause menu does.
- **bare** (`boolean`, default `false`): The column on its plate alone, without the stage and the hint chip, to lay over a game of your own. Its type is 20 px, or --ally-size.
- **autoplay** (`boolean`, default `true`): While on screen and untouched, a short run of play: calls, spent allies, recharges. Any input hands it to the reader.
- **colorScheme** (`'light' | 'dark' | 'system'`): Light or dark stage, or the reader’s; without it, the page’s color-scheme. The HUD keeps its colours on its plate on both.
- **className** (`string`): Classes for the root.
## Accessibility
- A list labelled Allies; each ally is a real button named with its state, such as “Gale ray, 1 of 1 charge” or “Gale ray, recharging, 40%” (in steps of 10, so it does not chatter), with aria-keyshortcuts for its number.
- Click, Enter or Space calls an ally; 1 to 4 call them while focus is inside. Focus shows a white ring on the dark plate and the ally’s name on a dark tag, which also shows on hover.
- A polite live region says what happened: called and how many are left, spent and recharging, refused while recharging, ready again.
- The creatures, the count and the name tag are decorative (aria-hidden); the button’s name carries their meaning, and spent is shown by colour and by the missing count and the fill, not by colour alone.
- Under reduced motion the states change at once: no bursts, rings, shakes, pops or breathing, no autoplay, and the fill steps without easing.
## Source
### ally-tracker/ally-tracker.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import {
useEffect,
useEffectEvent,
useRef,
useState,
type CSSProperties,
type KeyboardEvent,
} from 'react';
import { BeastArt, type AllyKind } from './beasts';
import { useAutoplay } from './use-autoplay';
import styles from './ally-tracker.module.css';
/*
* Ally tracker: the game HUD's column of companions, on its own dark plate so it reads on a light
* stage as well as a dark one. Each ally lends a power the player can call
* on a few times (its charges); once spent, it needs time to come back. At a glance:
*
* - Ready: the creature glows in its own colour (a thick stroke of the silhouette under a pale
* body, over a halo that is a blurred copy of the silhouette behind it, so the creature itself
* stays sharp), with "×N" charges at its top right.
* - Spent: the creature turns red, dark, with no count, and fills with a pale red from the bottom
* as it recharges (the fill is a copy of the art, clipped from the top to the silhouette's own
* height). Its red halo breathes slowly while it works.
*
* The moments of play animate on the creature, keyed so that each plays again: a call squashes it
* (anticipation), bursts it with a ring and settles, and the count pops; the last charge does the
* same, then shakes it into the red; a call on a spent ally is refused with a shake; when the fill
* reaches the top, the creature flashes back into its colour with a ring and the full count pops in.
*
* Uncontrolled, it keeps its own allies and recharges them on a clock that only runs while it is
* on screen in a visible tab and not paused; a demo plays a short run of calls while it is untouched.
* Given `allies`, it shows those (the game owns charges and recharge) and reports presses through
* `onUse`. Each ally is a button (click, Enter or Space), and 1–4 call them while focus is inside.
*/
export type { AllyKind };
export type AllyTrackerItem = {
/** Stable id: the same id is the same ally. */
id: string;
/** Its creature and colour. */
kind: AllyKind;
/** Its name, for the tag on hover or focus and for screen readers. */
label: string;
/** Charges left. 0 is spent: red, recharging. */
charges: number;
/** Charges when full. */
maxCharges: number;
/** While spent, how far it has recharged, from 0 to 1. */
recharge?: number;
};
/** Each creature's colour, and the top and height of its silhouette in % of its 48-unit box, so
the recharge fill rises over the creature and not over empty box. */
const KIND: Record = {
drake: { tint: '#08e6fd', top: 12, span: 76 },
ray: { tint: '#8fe04e', top: 1, span: 92 },
fox: { tint: '#f7630a', top: 4, span: 84 },
stag: { tint: '#efd52c', top: 0, span: 88 },
};
const DEFAULT_ALLIES: AllyTrackerItem[] = [
{ id: 'drake', kind: 'drake', label: 'Shell drake', charges: 1, maxCharges: 1 },
{ id: 'ray', kind: 'ray', label: 'Gale ray', charges: 1, maxCharges: 1 },
{ id: 'fox', kind: 'fox', label: 'Ember fox', charges: 2, maxCharges: 2 },
{ id: 'stag', kind: 'stag', label: 'Storm stag', charges: 3, maxCharges: 3 },
];
type Moment = 'use' | 'spent' | 'deny' | 'recharged';
/** The demo: calls at ms from its start, by ally id. Every ally ends full again before it loops. */
const DEMO: { at: number; id: string }[] = [
{ at: 900, id: 'stag' },
{ at: 1900, id: 'stag' },
{ at: 3000, id: 'fox' },
{ at: 4300, id: 'ray' },
{ at: 6000, id: 'ray' },
{ at: 7200, id: 'fox' },
{ at: 9000, id: 'drake' },
{ at: 10600, id: 'stag' },
];
const DEMO_LENGTH = 26000;
/** Recharge time while the demo plays, so a loop shows it whole. */
const DEMO_RECHARGE = 10;
export function AllyTracker({
allies,
defaultAllies = DEFAULT_ALLIES,
onUse,
onRecharged,
rechargeSeconds = 12,
paused = false,
bare = false,
autoplay = true,
colorScheme,
className = '',
}: {
/** The allies to show, controlled: the game owns charges and recharge, presses call onUse. Turns the demo off. */
allies?: AllyTrackerItem[];
/** Uncontrolled, the allies it starts with. */
defaultAllies?: AllyTrackerItem[];
/** Called with an ally's id when the player calls on it while it has a charge. */
onUse?: (id: string) => void;
/** Uncontrolled, called with an ally's id when it has recharged. */
onRecharged?: (id: string) => void;
/** Uncontrolled, how long a spent ally takes to recharge, in seconds. */
rechargeSeconds?: number;
/** Stops recharging, as a game's pause menu does. */
paused?: boolean;
/** The column on its plate alone, without the stage and the hint, to lay over a game of your own. */
bare?: boolean;
/** While on screen and untouched, a short run of play: calls, a spent ally, recharges. */
autoplay?: boolean;
/** Light or dark stage, or the reader's ('system'); without it, the page's color-scheme. The HUD keeps its colours. */
colorScheme?: 'light' | 'dark' | 'system';
className?: string;
}) {
const { ref: root, playing, visible, take } = useAutoplay(8000);
const controlled = allies !== undefined;
const [own, setOwn] = useState(defaultAllies);
const list = allies ?? own;
const demo = autoplay && playing && !controlled;
const [message, setMessage] = useState('');
const announce = (text: string) => setMessage((now) => (now === text ? `${text} ` : text));
/** The last moment of each ally, with a serial so the same moment plays again. */
const [moments, setMoments] = useState>({});
const serial = useRef(0);
const mark = (id: string, type: Moment) =>
setMoments((now) => ({ ...now, [id]: { type, n: ++serial.current } }));
// Moments read from changes, so a controlled tracker animates what the game does as well.
const previous = useRef(new Map());
const sync = useEffectEvent((items: AllyTrackerItem[]) => {
for (const ally of items) {
const before = previous.current.get(ally.id);
previous.current.set(ally.id, ally.charges);
if (before === undefined || before === ally.charges) continue;
if (ally.charges < before) {
mark(ally.id, ally.charges === 0 ? 'spent' : 'use');
announce(
ally.charges === 0
? `${ally.label} called, spent, recharging`
: `${ally.label} called, ${ally.charges} left`,
);
} else if (before === 0) {
mark(ally.id, 'recharged');
if (!controlled) onRecharged?.(ally.id);
announce(
`${ally.label} ready, ${ally.charges} ${ally.charges === 1 ? 'charge' : 'charges'}`,
);
}
}
});
useEffect(() => sync(list), [list]);
/** Calling on an ally: a charge spent, or a refusal while it recharges. */
const call = (id: string) => {
const ally = list.find((item) => item.id === id);
if (!ally) return;
if (ally.charges <= 0) {
mark(id, 'deny');
announce(`${ally.label} is recharging`);
return;
}
onUse?.(id);
if (!controlled)
setOwn((now) =>
now.map((item) =>
item.id === id ? { ...item, charges: item.charges - 1, recharge: 0 } : item,
),
);
};
const demoCall = useEffectEvent((id: string) => call(id));
// The recharge clock: uncontrolled, only while someone can see it and the game is not paused.
const seconds = demo ? DEMO_RECHARGE : rechargeSeconds;
const recharging = !controlled && own.some((ally) => ally.charges === 0);
const tick = useEffectEvent((ms: number) =>
setOwn((now) =>
now.map((ally) => {
if (ally.charges > 0) return ally;
const recharge = (ally.recharge ?? 0) + ms / (seconds * 1000);
return recharge < 1
? { ...ally, recharge }
: { ...ally, charges: ally.maxCharges, recharge: 0 };
}),
),
);
useEffect(() => {
if (!recharging || !visible || paused) return;
let last = performance.now();
const interval = window.setInterval(() => {
const now = performance.now();
tick(now - last);
last = now;
}, 100);
return () => window.clearInterval(interval);
}, [recharging, visible, paused]);
// The demo: a run of calls, again and again while it may play.
useEffect(() => {
if (!demo) return;
const timers: number[] = [];
const run = () => {
timers.push(...DEMO.map(({ at, id }) => window.setTimeout(() => demoCall(id), at)));
};
run();
const loop = window.setInterval(run, DEMO_LENGTH);
return () => {
timers.forEach((timer) => window.clearTimeout(timer));
window.clearInterval(loop);
};
}, [demo]);
const onKeyDown = (event: KeyboardEvent) => {
if (!controlled) take();
const index = Number(event.key) - 1;
if (event.altKey || event.ctrlKey || event.metaKey || !(index >= 0 && index < list.length))
return;
event.preventDefault();
call(list[index].id);
};
return (