# Title cards
> A game’s big serif title cards: a place, a landmark, a named enemy, a boss and a quest banner with a COMPLETE stamp, each revealed with gathering letters.
The titles a game lays across the middle of the screen when the player crosses a threshold. A location’s name glows (cool for a sanctum, warm for a region) over a subline between scroll ornaments; a landmark reads plain under its region; a named enemy gets a red rule; a boss’s epithet comes first, then its name slams in, white with a red edge and glow, and the card shakes. A quest shows its kind’s icon over a pale band, and completing it drops a COMPLETE stamp onto the band. Titles gather from wide letter-spacing as they fade in. Pick a card from the chips, or complete the quest.
A React component by Bruno Delorence: https://brunodelorence.com/components/title-cards. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: Games · Dialogs.
## Anatomy
1. **Plate**: A warm dark room, 13 em by 3.8 em of the title size (60 px on a wide stage, 26 px on a phone), lit a little at its centre; cards come and go inside it without moving the chips.
2. **Quest kind**: The quest’s icon and label (Main Quest, Side Quest, Trial) in small italic sans; the icon pops in first.
3. **Band**: A pale band that opens from the centre and stretches across the card, carrying the quest’s title in dark ink.
4. **Title**: Cinzel capitals and small capitals, never wrapped, gathering in from wide letter-spacing as they fade in.
5. **Stamp**: COMPLETE, dropped from large onto the band’s lower right with a flash of glow when `completed` turns on.
6. **Card chips**: One chip per card under the plate (`aria-pressed` on the shown one); picking the shown one replays it.
7. **Complete chip**: Toggles the quest’s stamp; from any other card it brings the quest in already completed.
## When to use
- Marking a threshold the player just crossed: a named place entered, a landmark found, a boss fight begun.
- A one-off announcement laid across the middle of the screen that the player reads in a second and that leaves on its own.
- Giving events a ranked weight: a location loudest, a landmark plainer, an enemy smaller with a red rule, a boss with a slam and a shake.
- Opening and closing quests, with a stamp that drops onto the quest’s band when it is completed.
- A cutscene or trailer beat that needs a cinematic title over the picture (`bare` drops the plate and chips).
## When not to use
- Routine feedback such as an item picked up or a save done. Use game toasts in a corner.
- Several messages that may arrive together: a game never stacks two title cards. Use a toast queue or a quest log.
- Text the player must act on or answer. Use a dialog box or a game modal.
- Tracking objectives over time. Use a quest log; this card announces a quest, it does not list its steps.
- Product headings or page titles outside a game. Use the page’s own heading styles.
## Installation
Install it with the shadcn CLI, into components/title-cards of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/title-cards.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 { TitleCards, type TitleCard } from './title-cards';
const CARDS: TitleCard[] = [
{ id: 'harbor', kind: 'location', tone: 'warm', title: 'Saltmere Harbor' },
{ id: 'warden', kind: 'boss', title: 'The Iron Warden', kicker: 'Keeper of the Lower Gate' },
{ id: 'gate', kind: 'quest', quest: 'main', title: 'Open the Lower Gate' },
];
export function Announcer({ card, done }: { card: string; done: boolean }) {
return ;
}
```
## States
- **Location, cool**: `tone="cool"`: the largest title, white with a blue edge and glow, its subline between two scroll ornaments.
- **Location, warm**: `tone="warm"`: a smaller cream title with a warm glow and no subline.
- **Landmark**: Plain cream, no glow, under its region between two leaf ornaments.
- **Enemy**: A smaller name under its region, with a red rule drawn from the centre.
- **Boss**: The epithet first, then the name slams in, white with a dark red edge and glow; the card shakes once.
- **Quest**: A main quest’s icon and label over its title on the pale band.
- **Quest complete**: `completed`: the band dims a touch and the COMPLETE stamp drops onto it.
- **Side quest and trial**: `quest="side"` and `quest="trial"` change the icon and the label; `questLabel` names it otherwise.
- **Bare**: `bare`: the card alone at 60 px, no plate or chips, to lay over a game’s own picture.
- **Phone width**: At 375 px the title size follows the width (about 28 px), the plate grows taller and the chips tighten; the card scales as one.
- **Light**: `colorScheme="light"`: a soft shadow under the plate and pale chips. The card’s own colours never change.
- **Dark**: `colorScheme="dark"`: a brighter plate edge, a deeper shadow and dark chips.
## How it works
- A card is a layer. Showing another card, or the same one again, sends the shown layer out (it fades in 260 ms) and mounts a new one in the same grid cell; the newcomer’s parts wait --wait (260 ms when something is leaving), so two titles never stack, as in a game.
- Each part plays its keyframes as it mounts. A title gathers: it fades in while its letter-spacing and its text-indent shrink together from 0.42 em to 0.02 em (the indent balances the space after the last letter, so the line stays centred). A location’s glow then swells past its resting text-shadow and settles; its subline rises in while the scroll ornaments slide outwards.
- An enemy’s red rule sits in a grid with the name and reaches 0.75 em past it on each side; it draws from the centre (scale from 0 on x) once the name has landed. A boss’s epithet fades in first; the name slams from 1.32× with wide spacing on an overshooting curve, its red glow flares, and the whole card shakes for 320 ms.
- A quest’s icon pops, its label fades, the band opens from the centre and its title gathers on it. The COMPLETE stamp mounts when completed is set: it drops from 2.6× to just under its size and settles, with a flash of warm glow; when the quest arrives already completed, the stamp waits for the band.
- The titles are set in Cinzel, a free inscriptional serif whose lowercase letters are small capitals, loaded once from Google Fonts (a stylesheet link the component adds to the document), with Georgia behind it. The boss’s and the sanctum’s edges are a text stroke painted under the fill (paint-order), and every glow is a text- or box-shadow, so the letters stay sharp.
- Every size is in em of the plate’s font size (60 px wide, down to 26 px on a phone through a container query, or --title-size), so a card scales as one; small text never goes under 11 px. The cards sit on their own warm dark plate, lit a little at its centre, so their colours stay the same on a light or a dark page; only the plate’s edge, its shadow and the chips follow the colour scheme. bare draws a card alone, to lay over a game.
- Uncontrolled, chips under the plate pick a card (the shown one replays) and complete the quest, and a demo plays a short run of play (a sanctum, a region, a landmark, an enemy, a boss, a quest and its completion) while it is on screen and untouched; any input hands it to the reader.
## API reference
- **cards** (`TitleCard[]`, default `sanctum, region, landmark, enemy, boss, quest`): The cards, each { id, kind, title, kicker?, tone?, quest?, questLabel?, label? }. kind is 'location' | 'landmark' | 'enemy' | 'boss' | 'quest'; kicker is a location's subline, a landmark's or an enemy's region, or a boss's epithet; tone ('cool' | 'warm') sets a location's glow; quest ('main' | 'side' | 'trial') picks a quest's icon; label names its chip.
- **card** (`string`): The id of the card shown, controlled: changing it plays the next card in. The demo is off, and the chips ask onCardChange.
- **defaultCard** (`string`, default `'sanctum'`): Uncontrolled, the card it starts with.
- **onCardChange** (`(card: string) => void`): Asked when a chip is picked (the shown card’s chip replays it).
- **completed** (`boolean`): Whether a quest card is completed, controlled: turning it on drops the COMPLETE stamp onto the band.
- **onCompletedChange** (`(completed: boolean) => void`): Asked when the Complete chip is toggled.
- **bare** (`boolean`, default `false`): The card alone, without its plate and chips, to lay over a game. Its titles are 60 px, or --title-size.
- **autoplay** (`boolean`, default `true`): While on screen and untouched, a short run of play: each card in turn, then the quest completed. Uncontrolled only.
- **colorScheme** (`'light' | 'dark' | 'system'`): Forces light or dark for the plate’s edge and shadow and the chips; by default it follows the page. The cards keep their colours.
- **className** (`string`): Added to the root.
## Accessibility
- The titles, kickers and labels are real text; the ornaments, the enemy’s rule and the quest icons are aria-hidden.
- A polite live region reads each new card (“Mire Stalker. Brackwood Marsh.”) and a completed quest (“Main Quest complete: The Drowned Archive.”). A leaving card is hidden from assistive technology at once.
- The chips are toggle buttons (aria-pressed) in a labelled group, reachable by Tab, with a :focus-visible ring; pressing the shown card’s chip replays it.
- Small text never goes under 11 px, and every colour pair keeps its contrast on the plate, whatever the page’s colour scheme.
- Reduced motion: no gathering, slams, shakes, pops, draws or drops; each part only fades in for 200 ms. The demo never plays.
## Source
### title-cards/title-cards.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import {
useCallback,
useEffect,
useEffectEvent,
useLayoutEffect,
useRef,
useState,
type CSSProperties,
} from 'react';
import { LeafDash, QuestIcon, ScrollEnd, type QuestKind } from './ornaments';
import { useAutoplay } from './use-autoplay';
import styles from './title-cards.module.css';
/*
* Title cards: the big serif titles a game lays across the middle of the screen when the player
* crosses a threshold. Five kinds, each with its own weight:
*
* - location: you entered a named place. The largest title, glowing (cool for a sanctum, warm for a
* region), with an optional subline between two scroll ornaments (its keeper, its trial).
* - landmark: you found a point of interest. Plain cream, no glow, under a small kicker naming the
* region, between two leaf ornaments.
* - enemy: a named enemy noticed you. Smaller, with a red rule under it that says threat.
* - boss: the fight starts. The epithet reads first; then the name slams in, white with a dark red
* edge and a red glow, and the card shakes once.
* - quest: a quest began. Its kind's icon and label, then its title on a pale band. When it is
* completed, a COMPLETE stamp drops onto the band.
*
* How it moves: a card is a layer. A new card (or a replay) sends the shown layer out (it fades,
* 260 ms) and mounts a new one, whose parts play keyframes on mount, a little later if something
* was leaving: a game never stacks two title cards. Titles gather from wide letter-spacing as they
* fade in (letter-spacing and text-indent animate together, so the line stays centred), then their
* glow swells. Kickers fade while their ornaments slide outwards; the enemy's rule draws from the
* centre; the band opens from the centre. The stamp mounts when the quest is completed and plays
* its drop (after the band if both arrive together).
*
* The titles are set in Cinzel (a free inscriptional serif, loaded once from Google Fonts, falling
* back to the system's serif). The cards sit on their own dark plate, so they read on a light page
* or a dark one; `bare` draws them alone, to lay over a game. Uncontrolled, chips under the plate
* pick a card (the shown one replays) and a demo plays a short run of play while on screen and
* untouched.
*/
export type { QuestKind };
export type TitleCardKind = 'location' | 'landmark' | 'enemy' | 'boss' | 'quest';
export type TitleCard = {
/** Stable id, for `card` and the chips. */
id: string;
kind: TitleCardKind;
/** The title, in title case: the face sets lowercase as small capitals. */
title: string;
/** location: the subline; landmark and enemy: the region; boss: the epithet. */
kicker?: string;
/** location only: a cool (sacred) or warm (region) glow. */
tone?: 'cool' | 'warm';
/** quest only: its kind, for the icon. */
quest?: QuestKind;
/** quest only: the label beside the icon. Defaults to Main Quest, Side Quest or Trial. */
questLabel?: string;
/** The chip's name. Defaults to the title. */
label?: string;
};
export const DEFAULT_CARDS: TitleCard[] = [
{
id: 'sanctum',
kind: 'location',
tone: 'cool',
title: 'Tidewell Sanctum',
kicker: 'Keeper Ilsa Morrow',
label: 'Sanctum',
},
{ id: 'region', kind: 'location', tone: 'warm', title: 'Emberfall Vale', label: 'Region' },
{
id: 'landmark',
kind: 'landmark',
title: 'Ashen Watchtower',
kicker: 'Westreach Highlands',
label: 'Landmark',
},
{
id: 'enemy',
kind: 'enemy',
title: 'Mire Stalker',
kicker: 'Brackwood Marsh',
label: 'Enemy',
},
{
id: 'boss',
kind: 'boss',
title: 'Tidebound Colossus',
kicker: 'Warden of the Sunken Bell',
label: 'Boss',
},
{
id: 'quest',
kind: 'quest',
quest: 'main',
title: 'The Drowned Archive',
label: 'Quest',
},
];
const QUEST_LABEL: Record = {
main: 'Main Quest',
side: 'Side Quest',
trial: 'Trial',
};
/** How long a leaving card takes to fade (the next one waits for it). */
const LEAVE = 260;
/** The demo: a short run of play, as steps at ms from its start. */
const DEMO: ({ at: number } & ({ card: string } | { complete: boolean }))[] = [
{ at: 0, complete: false },
{ at: 0, card: 'sanctum' },
{ at: 3600, card: 'region' },
{ at: 6600, card: 'landmark' },
{ at: 9600, card: 'enemy' },
{ at: 12400, card: 'boss' },
{ at: 16600, card: 'quest' },
{ at: 18900, complete: true },
];
const DEMO_LENGTH = 22400;
/** Cinzel, from Google Fonts, added to the document once. */
const FONT_HREF = 'https://fonts.googleapis.com/css2?family=Cinzel:wght@600..900&display=swap';
function useTitleFont() {
useEffect(() => {
if (document.querySelector('link[data-title-cards-font]')) return;
const link = document.createElement('link');
link.rel = 'stylesheet';
link.href = FONT_HREF;
link.dataset.titleCardsFont = '';
document.head.append(link);
}, []);
}
type Layer = {
key: number;
card: TitleCard;
phase: 'in' | 'out';
/** It waits for a leaving card before it plays. */
late: boolean;
/** Its stamp arrived with it (so it drops after the band), and, when leaving, whether it had one. */
stampWithEntry: boolean;
complete?: boolean;
};
const say = (card: TitleCard | undefined, complete: boolean) => {
if (!card) return '';
if (card.kind === 'quest') {
const label = card.questLabel ?? QUEST_LABEL[card.quest ?? 'main'];
return complete ? `${label} complete: ${card.title}.` : `${label}: ${card.title}.`;
}
return card.kicker ? `${card.title}. ${card.kicker}.` : `${card.title}.`;
};
export type TitleCardsProps = {
className?: string;
/** The cards to show. */
cards?: TitleCard[];
/** The card shown (controlled). */
card?: string;
/** The card it starts with, uncontrolled. */
defaultCard?: string;
/** Asked when a chip is picked. */
onCardChange?: (card: string) => void;
/** A quest card is completed: its stamp shows (controlled). */
completed?: boolean;
/** Asked when the Complete chip is toggled. */
onCompletedChange?: (completed: boolean) => void;
/** The card alone, without its plate and chips, to lay over a game. */
bare?: boolean;
/** Plays a short run of play while on screen and untouched (uncontrolled only). */
autoplay?: boolean;
colorScheme?: 'light' | 'dark' | 'system';
};
export function TitleCards({
className,
cards = DEFAULT_CARDS,
card: cardProp,
defaultCard = 'sanctum',
onCardChange,
completed: completedProp,
onCompletedChange,
bare = false,
autoplay = true,
colorScheme,
}: TitleCardsProps) {
useTitleFont();
const controlled = cardProp !== undefined;
const [ownCard, setOwnCard] = useState(defaultCard);
const id = controlled ? cardProp : ownCard;
const [ownCompleted, setOwnCompleted] = useState(false);
const completed = completedProp ?? ownCompleted;
const current = cards.find((item) => item.id === id) ?? cards[0];
const { ref, take, playing } = useAutoplay();
const demo = playing && autoplay && !controlled && completedProp === undefined;
const [replays, setReplays] = useState(0);
const counter = useRef(0);
const [layers, setLayers] = useState(() =>
current ? [{ key: 0, card: current, phase: 'in', late: false, stampWithEntry: completed }] : [],
);
const [said, setSaid] = useState('');
// A new card or a replay: the shown layer leaves, a new one comes in behind it.
const showKey = `${current?.id}|${replays}`;
const lastKey = useRef(showKey);
const completedRef = useRef(completed);
completedRef.current = completed;
useLayoutEffect(() => {
if (lastKey.current === showKey || !current) return;
lastKey.current = showKey;
const key = ++counter.current;
setLayers((old) => {
const leaving = old
.filter((layer) => layer.phase === 'in')
.map((layer): Layer => ({ ...layer, phase: 'out', complete: completedRef.current }));
const gone = old.filter((layer) => layer.phase === 'out');
return [
...gone,
...leaving,
{
key,
card: current,
phase: 'in',
late: leaving.length > 0,
stampWithEntry: completedRef.current,
},
];
});
setSaid(say(current, completedRef.current));
// A safety net: leavers drop out on their animation's end, or after this at the latest.
const timer = window.setTimeout(
() => setLayers((now) => now.filter((layer) => layer.phase === 'in' || layer.key > key)),
LEAVE + 200,
);
return () => window.clearTimeout(timer);
}, [showKey]);
// Completing the shown quest (after it arrived) is news of its own.
const lastCompleted = useRef(completed);
useEffect(() => {
if (lastCompleted.current === completed) return;
lastCompleted.current = completed;
if (current?.kind === 'quest' && completed) setSaid(say(current, true));
}, [completed, current]);
const dropOut = useCallback((key: number) => {
setLayers((now) => now.filter((layer) => layer.key !== key));
}, []);
const pick = useCallback(
(next: string) => {
if (next === id) setReplays((n) => n + 1);
else if (!controlled) setOwnCard(next);
onCardChange?.(next);
},
[id, controlled, onCardChange],
);
const setCompleted = useCallback(
(next: boolean) => {
if (completedProp === undefined) setOwnCompleted(next);
onCompletedChange?.(next);
},
[completedProp, onCompletedChange],
);
// The demo, on its own clock: it restarts from the top each time it is handed back.
const step = useEffectEvent((item: (typeof DEMO)[number]) => {
if ('card' in item) {
if (item.card === ownCard) setReplays((n) => n + 1);
else setOwnCard(item.card);
} else setOwnCompleted(item.complete);
});
useEffect(() => {
if (!demo) return;
const ids: number[] = [];
const run = (start: number) => {
for (const item of DEMO) ids.push(window.setTimeout(() => step(item), start + item.at));
ids.push(window.setTimeout(() => run(0), start + DEMO_LENGTH));
};
run(0);
return () => ids.forEach((timer) => window.clearTimeout(timer));
}, [demo]);
const questShown = current?.kind === 'quest';
return (
{layers.map((layer) => {
const out = layer.phase === 'out';
const stamp = out ? !!layer.complete : completed;
// The shown card follows edits to its data (a new title under the same id).
const fresh = !out && current && layer.card.id === current.id ? current : layer.card;
return (
dropOut(layer.key) : undefined}
/>
);
})}