# Heart meter
> A game HUD heart meter: quarter hearts, yellow extra hearts, a hit flash and shake, a beating last heart, and heals that fill one quarter at a time.
The row of hearts in a game HUD’s corner, on its own dark plate. Health is counted in quarters, so a partial heart fills by quadrants; yellow extra hearts follow the red ones and are lost first. A hit flashes the lost quarters white and shakes the row, one heart or less makes the last heart beat red, a heal fills quarter by quarter with a pop per heart, and pickups show their recovery chip: hearts restored, Full Recovery, or + 10 extra hearts.
A React component by Bruno Delorence: https://brunodelorence.com/components/heart-meter. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: Games · HUD.
## Anatomy
1. **Plate**: The `role="meter"` box: a dark plate 0.7 heart in at the sides and a third of one at the top and bottom, with a hairline just inside its edge, so the row reads on a light page and a dark one.
2. **Row**: A grid of one column per heart, 3/13 of a heart apart, wrapping every `perRow` (15). Red hearts come first, then the yellow ones.
3. **Full heart**: One heart of health: a red fill over its dark container, 13 wide by 12 tall in the kit’s proportions (`size` sets the width, 24 px by default).
4. **Partial heart**: Health counts in quarters: a partial heart is clipped to its quadrants, top left first, then bottom left, bottom right and top right. Here a quarter.
5. **Empty container**: A heart container with no health in it, drawn dark: `max` sets how many there are.
6. **Extra heart**: A temporary yellow heart (`extra`) after the red ones. A hit takes these first; one spent whole flashes out from its place.
7. **Recovery chip**: What a pickup restores, on the same plate: one to five hearts, a heart with the count past five, Full Recovery, or a yellow heart and + 10.
## When to use
- Health in a game HUD that the player reads at a glance as a count of hits left, not as a percentage.
- Damage and healing in small, countable steps: a quarter heart per graze, a heart per hit, three per meal.
- A health pool that grows over the game, one heart container at a time, up to 30.
- Temporary bonus health from food or potions that should read as different and be lost first: the yellow hearts.
- A HUD that has to warn without words: the last heart beats and glows red at one heart or less.
## When not to use
- Health in the hundreds or with fine-grained damage. Use a health bar, with a number if it matters.
- A resource the player spends and that refills on its own, such as sprint. Use a stamina wheel.
- Shields, armour or anything that should read as a second layer over health. Use a separate bar or a ring over the hearts.
- A rating or a score out of five outside a game. Use a star rating, which a reader sets and does not lose.
- Progress through a task or a level. Use a progress bar; hearts read as something that can run out.
## Installation
Install it with the shadcn CLI, into components/heart-meter of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/heart-meter.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 { HeartGauge } from './heart-meter';
export function PlayerHud({ health, containers, extra }: { health: number; containers: number; extra: number }) {
return ;
}
```
## States
- **Full**: `value` equal to `max`: every container full.
- **Damaged**: `value={3.5}` of 5: the hearts empty from the right, the partial one by quadrants.
- **Quarters**: One heart at ¼, ½, ¾ and full: top left, then the left half, then all but the top right.
- **Low**: `value={0.75}`: at `low` hearts or fewer with no yellow ones, the last heart double-beats with a red glow and the hairline blinks.
- **Down**: `value={0}`: every container dark, nothing beats; the meter says “down”.
- **Extra hearts**: `extra={2.5}`: yellow hearts after the red ones, also counted in quarters and lost first.
- **Low with extra**: `value={0.5}` with `extra={1}`: a yellow heart still stands in front, so the last red heart does not beat.
- **Two rows**: `max={20}` with `perRow={10}`: the row wraps; containers, red and yellow together stop at 30.
- **No plate**: HeartGauge with `plate={false}`, for a HUD whose own scene or panel gives the hearts their footing.
- **Recovery chips**: HeartChip for each kind of pickup: three hearts, eight (a count), Full Recovery and + 10 extra.
- **Playground**: HeartMeter with `autoplay={false}`: the row, the chip’s place and the five actions, by button or key.
## How it works
- Every heart is one original SVG path in a 26 × 24 box, drawn three times: the dark container, the coloured fill clipped to 0–4 quadrants, and for a moment after a hit a white copy clipped to what it held before. The four quadrant clips are defined once per row; quarters fill top left, bottom left, bottom right, then top right, split at the notch and just above the middle.
- The row keeps what it shows apart from its value: a drop is shown at once, a rise steps one quarter every 45 ms. Each render compares every heart’s quarters with the last one, by heart, to find hits (a white flash that fades over 460 ms where the lost quarters were), completions (the fill pops from 1.24× with a brief brightening) and newcomers (a new container or yellow heart pops in with an overshoot, 40 ms after the one before, a container with a soft spark).
- A hit also shakes the whole row once, a 280 ms horizontal shake that settles, through the Web Animations API. At one heart or less, with no yellow hearts left, the last red heart gives a double beat every second with a red glow and the plate’s hairline blinks red, until healed.
- Yellow extra hearts follow the red ones in the same grid and are spent first; one spent whole flashes out from its place before it is dropped. Containers, red and yellow hearts together stop at 30, wrapping every 15 (the perRow prop).
- Proportions come from the kit: a heart 13 wide and 12 tall, 3 apart, on a plate padded 0.7 heart at the sides and a third of one at the top and bottom, with a hairline just inside its edge. Everything is a multiple of one heart’s width, 24 px by default and less when the stage is too narrow for a full row (a container query unit).
- The recovery chip is the same plate: one to five hearts, or a heart with the count past five, or a heart and a green label, “Full Recovery” or “+ 10”. In the playground it wipes in from the left, holds for 1.9 s and fades.
- The playground runs a 23.5-second scripted fight while on screen and untouched: three hits down to one heart, a meal, a golden dish, two hits into the yellow, a new container, a heavy hit through the yellow and another to under a heart, then an elixir. Any real press hands it over.
- The red, yellow, dark containers, plate and green label are the same on any scheme, as a game’s are; only the plate’s outer edge and the buttons follow the page through light-dark() tokens.
## API reference
- **value** (`number`): HeartGauge: health in hearts, by quarters, from 0 to max. On HeartMeter it turns the playground into a plain display of this value.
- **max** (`number`, default `3 (HeartMeter: 5)`): Heart containers, 1 to 30: how much health there can be. On HeartMeter without value, the count the fight starts with.
- **extra** (`number`, default `0`): Temporary extra hearts, drawn yellow after the red ones and lost first.
- **perRow** (`number`, default `15`): Hearts per row before the row wraps.
- **low** (`number`, default `1`): At this many hearts or fewer (and no yellow ones), the last heart beats and glows red.
- **plate** (`boolean`, default `true`): HeartGauge: the dark plate behind the row.
- **size** (`number`): One heart’s width in px. Without it, 32 on a stage 520 px or wider, else 24, and less when the stage is too narrow for a full row.
- **label** (`string`, default `'Health'`): HeartGauge: what a screen reader calls the meter.
- **pickup** (`{ kind: 'hearts'; amount: number } | { kind: 'full' } | { kind: 'extra'; amount: number }`): HeartChip: what a pickup gives: hearts restored (a count past five), Full Recovery, or + extra hearts.
- **autoplay** (`boolean`, default `true`): HeartMeter: while on screen and untouched, a scripted fight plays the actions by itself.
- **colorScheme** (`'light' | 'dark' | 'system'`): Light or dark plate edge and buttons, or the reader’s (system); without it, the page’s color-scheme.
- **className** (`string`): Added to the root element.
## Accessibility
- The row is a meter (role="meter") with its value in hearts and a value text such as “3¾ of 5 hearts, plus 10 extra, low”; the hearts themselves are aria-hidden SVG.
- A recovery chip is an image with a label (“Restores 3 hearts”, “Full recovery”, “10 extra hearts”).
- The actions are real buttons with their keys in aria-keyshortcuts. The stage can take focus: then H takes a hit, E eats, R drinks an elixir, G eats a golden dish and U adds a heart container.
- What each action did is announced through a polite live region, only for the reader’s own play, never for the scripted fight.
- Under reduced motion the fight does not play, heals jump straight to the value, there is no shake, pop or beat (a steady red glow marks low health) and chips only fade.
## Source
### heart-meter/heart-meter.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import {
useEffect,
useId,
useRef,
useState,
type CSSProperties,
type ReactNode,
type KeyboardEvent as ReactKeyboardEvent,
} from 'react';
import { useAutoplay } from './use-autoplay';
import styles from './heart-meter.module.css';
/*
* Heart meter: the row of hearts in a game HUD's corner that tells the player how much damage they
* can still take.
*
* - HeartGauge is the row alone, driven by props: `value` hearts of health out of `max` heart
* containers, counted in quarters, and `extra` temporary yellow hearts after the red ones, which
* a hit takes first. An empty container is a dark heart; a partial one fills by quadrants, top
* left first, then bottom left, bottom right and top right, so a quarter left is the top-left
* corner.
* - Every heart is the same small SVG path drawn three times: the dark container, the coloured
* fill clipped to 0–4 quadrants (four shared clip paths), and, for a moment after a hit, a white
* copy clipped to what it held before, which flashes and fades where the lost quarters were.
* - The gauge keeps what it shows apart from `value`: a drop is shown at once (the white flash and
* a short shake of the whole row), a rise fills quarter by quarter, 45 ms each, and every heart
* that completes gives a small pop. New containers and new yellow hearts pop in, one after the
* other. At one heart or less (and no yellow hearts), the last heart beats and glows red.
* - Like the kit's menus, the row sits on its own dark plate (a hairline inside its edge), so the
* red, the yellow and the dark containers read the same on a white page and a black one.
* - HeartChip is the recovery chip a pickup shows: hearts restored (one heart and a count past
* five), "Full Recovery", or a yellow heart and "+ 10" for extra hearts.
* - HeartMeter is a playground around them: the row on a plain stage, the last pickup's chip
* under it, and five actions (take a hit, eat, drink an elixir, eat a golden dish, gain a heart
* container), by buttons or keys. While on screen and untouched, a short scripted fight plays
* them by itself. Give it `value` and it is a plain display instead.
*/
/** The heart, in a 26 × 24 box: wide lobes, a shallow notch, a near-point at the bottom. */
const HEART =
'M13 23.4 C12.6 23.4 12.2 23.2 11.9 22.9 L2.6 13.6 C0.9 11.9 0 9.7 0 7.3 C0 3.2 3.1 0.4 6.8 0.4 C9.4 0.4 11.6 1.7 13 3.8 C14.4 1.7 16.6 0.4 19.2 0.4 C22.9 0.4 26 3.2 26 7.3 C26 9.7 25.1 11.9 23.4 13.6 L14.1 22.9 C13.8 23.2 13.4 23.4 13 23.4 Z';
/** Where the quadrants meet: the notch's x, and a little above the middle. */
const MID_X = 13;
const MID_Y = 11.5;
/** The clip of each quarter count: top left; left half; left half and bottom right. */
const QUARTERS = [
'',
`M0 0 H${MID_X} V${MID_Y} H0 Z`,
`M0 0 H${MID_X} V24 H0 Z`,
`M0 0 H${MID_X} V${MID_Y} H26 V24 H0 Z`,
];
/** A heal fills one quarter this often, in ms. */
const STEP = 45;
/** The most hearts (red and yellow together) the row draws. */
const MOST = 30;
type Kind = 'red' | 'gold';
/** One heart's art: the dark container, the white flash of a hit, and the fill. */
function HeartArt({
q,
clip,
ghost,
pop,
bare = false,
}: {
q: number;
clip: string;
ghost?: { key: number; from: number };
pop?: number;
/** No dark container: a spent yellow heart's last flash. */
bare?: boolean;
}) {
const clipOf = (quarters: number) => (quarters >= 4 ? undefined : `url(#${clip}-${quarters})`);
return (
);
}
/** The four quadrant clips, once per gauge, in the heart's own 26 × 24 units. */
function Clips({ id }: { id: string }) {
return (
);
}
/** "3¾": hearts in quarters, as a player reads them. */
function hearts(value: number) {
const whole = Math.floor(value + 1e-6);
const part = ['', '¼', '½', '¾'][Math.round((value - whole) * 4) % 4];
return whole || !part ? `${whole}${part}` : part;
}
type Effects = {
/** Each slot's quarters at the last render, by slot key. */
seen: Record;
/** A slot's last hit: what it held before, keyed so the flash restarts. */
ghosts: Record;
/** A red slot's last completion, keyed so the pop restarts. */
pops: Record;
/** Slots that arrived after the first render, with their place in the arrival. */
born: Record;
/** Yellow hearts just spent: drawn as a fading flash where they were, then dropped. */
leaving: { key: string; from: number; tick: number }[];
/** Counts the hits, for the shake. */
hits: number;
tick: number;
};
export type HeartGaugeProps = {
/** Health, in hearts, by quarters: from 0 to `max`. */
value: number;
/** Heart containers: how much health there can be (1 to 30). */
max?: number;
/** Temporary extra hearts, drawn yellow after the red ones and lost first. */
extra?: number;
/** Hearts per row before the row wraps. */
perRow?: number;
/** At this many hearts or fewer (and no yellow ones), the last heart beats. */
low?: number;
/** The dark plate behind the row. */
plate?: boolean;
/** One heart's width in px; without it, 24 (it shrinks to fit a narrow stage). */
size?: number;
/** What a screen reader calls it. */
label?: string;
className?: string;
};
export function HeartGauge({
value,
max = 3,
extra = 0,
perRow = 15,
low = 1,
plate = true,
size,
label = 'Health',
className = '',
}: HeartGaugeProps) {
const id = useId().replace(/:/g, '');
const most = Math.min(MOST, Math.max(1, Math.round(max)));
const target = Math.round(Math.min(most, Math.max(0, value)) * 4);
const extraQ = Math.round(Math.min(MOST - most, Math.max(0, extra)) * 4);
// What is shown: a drop at once, a rise quarter by quarter (all at once under reduced motion).
const [shown, setShown] = useState(target);
const [reduced, setReduced] = useState(false);
useEffect(() => {
const motion = window.matchMedia('(prefers-reduced-motion: reduce)');
const read = () => setReduced(motion.matches);
read();
motion.addEventListener('change', read);
return () => motion.removeEventListener('change', read);
}, []);
if (shown > target || (reduced && shown !== target)) setShown(target);
useEffect(() => {
if (shown >= target) return;
const timer = window.setTimeout(() => setShown((q) => Math.min(target, q + 1)), STEP);
return () => window.clearTimeout(timer);
}, [shown, target]);
const now = Math.min(shown, target);
// The slots, red then yellow, each with its quarters.
const slots: { key: string; kind: Kind; q: number }[] = [];
for (let i = 0; i < most; i++)
slots.push({ key: `r${i}`, kind: 'red', q: Math.min(4, Math.max(0, now - i * 4)) });
for (let i = 0; i * 4 < extraQ; i++)
slots.push({ key: `g${i}`, kind: 'gold', q: Math.min(4, extraQ - i * 4) });
// What changed since the last render: hits flash, completions pop, newcomers pop in.
const [fx, setFx] = useState(() => ({
seen: Object.fromEntries(slots.map((slot) => [slot.key, slot.q])),
ghosts: {},
pops: {},
born: {},
leaving: [],
hits: 0,
tick: 0,
}));
const changed =
slots.length !== Object.keys(fx.seen).length ||
slots.some((slot) => fx.seen[slot.key] !== slot.q);
if (changed) {
const next: Effects = {
seen: {},
ghosts: { ...fx.ghosts },
pops: { ...fx.pops },
born: {},
leaving: fx.leaving.filter((gone) => !slots.some((slot) => slot.key === gone.key)),
hits: fx.hits,
tick: fx.tick,
};
let hit = false;
let arrival = 0;
for (const slot of slots) {
const before = fx.seen[slot.key];
next.seen[slot.key] = slot.q;
if (before === undefined) {
next.born[slot.key] = arrival++;
continue;
}
if (fx.born[slot.key] !== undefined) next.born[slot.key] = fx.born[slot.key];
if (slot.q < before) {
next.ghosts[slot.key] = { key: ++next.tick, from: before };
hit = true;
} else if (slot.q === 4 && before < 4 && slot.kind === 'red') {
next.pops[slot.key] = ++next.tick;
}
}
// A yellow heart spent whole flashes out from its last place (a red container that goes
// away, as when the playground starts over, just goes).
for (const [key, before] of Object.entries(fx.seen))
if (!(key in next.seen) && key[0] === 'g' && before > 0) {
next.leaving.push({ key, from: before, tick: ++next.tick });
hit = true;
}
next.leaving.sort((a, b) => Number(a.key.slice(1)) - Number(b.key.slice(1)));
if (hit) next.hits++;
setFx(next);
}
// Spent yellow hearts are dropped once their flash is over.
useEffect(() => {
if (!fx.leaving.length) return;
const timer = window.setTimeout(() => setFx((f) => ({ ...f, leaving: [] })), 480);
return () => window.clearTimeout(timer);
}, [fx.leaving]);
// A hit shakes the row: short, sharp, settling.
const row = useRef(null);
const shakes = useRef(fx.hits);
useEffect(() => {
if (fx.hits === shakes.current) return;
shakes.current = fx.hits;
if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;
row.current?.animate(
[
{ translate: '0 0' },
{ translate: 'calc(var(--heart) * -0.16) 0' },
{ translate: 'calc(var(--heart) * 0.13) 0' },
{ translate: 'calc(var(--heart) * -0.08) 0' },
{ translate: 'calc(var(--heart) * 0.04) 0' },
{ translate: '0 0' },
],
{ duration: 280, easing: 'cubic-bezier(0.3, 0.6, 0.4, 1)' },
);
}, [fx.hits]);
const reds = Math.min(4 * most, now);
const isLow = reds > 0 && reds <= low * 4 && extraQ === 0;
const beat = isLow ? `r${Math.ceil(reds / 4) - 1}` : '';
const columns = Math.max(1, Math.min(perRow, slots.length + fx.leaving.length));
const text =
`${hearts(target / 4)} of ${most} ${most === 1 ? 'heart' : 'hearts'}` +
(extraQ ? `, plus ${hearts(extraQ / 4)} extra` : '') +
(target === 0 ? ', down' : isLow ? ', low' : '');
return (