# Action prompts
> A game HUD’s context-sensitive button prompts: each context brings its set of verbs and button glyphs, swapped with a stagger.
The corner of a game screen that says what the buttons do right now: Jump X and Let go B on a wall, Throw R while carrying, Sort, Back and Select in a menu. Each verb sits beside its button drawn in the controller’s shape (face disc, shoulder key, trigger, stick, d-pad). Changing context swaps the set prompt by prompt, keeping the ones that still apply; emphasised prompts glow, and pressing one dips its glyph with a ring of light. Each prompt sits on its own dark plate, so it reads on a light page or a dark one. Pick a context from the chips, then press the prompts or their letters.
A React component by Bruno Delorence: https://brunodelorence.com/components/action-prompts. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: Games · Controls.
## Anatomy
1. **HUD corner**: Room for four prompts, the list pinned to its foot with its right edge a little right of centre, so a set of any size sits about the middle. `bare` leaves it out.
2. **Context chips**: Small neutral chips under the prompts, one per set, to try each context. Drawn only without `bare` and with more than one set.
3. **Current context**: The context shown, filled with the page’s ink and marked `aria-pressed`; any other asks `onContextChange`.
4. **Prompt list**: The set as a list named after its context, lined up on the right; its size comes from `--prompt-size`, or from the component’s width.
5. **Emphasised prompt**: A prompt with `emphasis`: its plate gets a warm rim and a soft light behind it that flares as it arrives, then breathes.
6. **Verb**: What the button does, in italics and on one line; it brightens on hover and flashes when pressed.
7. **Shoulder glyph**: L or R as a key with its outer top corner cut off, sized in em so it scales with the verb.
8. **Face glyph**: A disc with the letter upright and bold: A, B, X, Y, + or −. Its letter on the keyboard presses it too.
## When to use
- A game HUD where the same buttons do different things by context: on a wall, while carrying, in a menu.
- Telling the player which button does what right now, as a verb beside the button drawn in the controller’s shape.
- Swapping one context’s actions for the next without a jump: prompts that still apply stay and glide, the rest leave and the new ones slide in.
- Drawing the eye to a new or time-sensitive action (a charge to detonate, a thing to throw) with `emphasis`.
- A row of controls at the foot of a game menu (Sort, Back, Select), with `layout="row"` and `bare`.
## When not to use
- A list of every control in the game. Use a controls screen or a table of buttons; prompts show only what applies now.
- Keyboard shortcuts in a desktop app or a web tool. Use a shortcut hint with key caps, or the menu item’s own shortcut.
- A single glyph inside a sentence or a tutorial line. Use the controller glyphs on their own.
- An action the player must confirm or read before going on. Use a dialog or a toast with its own buttons.
- Ordinary web buttons dressed as a game. Use buttons; the glyph only means something with a controller in hand.
## Installation
Install it with the shadcn CLI, into components/action-prompts of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/action-prompts.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 { ActionPrompts, type ActionSet } from './action-prompts';
const SETS: ActionSet[] = [
{ id: 'roam', label: 'Roam', prompts: [] },
{
id: 'climb',
label: 'Climb',
prompts: [
{ label: 'Jump', button: 'X' },
{ label: 'Let go', button: 'B' },
],
},
{
id: 'carry',
label: 'Carry',
prompts: [
{ label: 'Throw', button: 'R', emphasis: true },
{ label: 'Cancel', button: 'B' },
],
},
];
export function ControlsHint({ context }: { context: 'roam' | 'climb' | 'carry' }) {
return ;
}
```
## States
- **Two prompts**: On a wall: Jump X and Let go B, two face buttons.
- **Emphasis**: Carrying: Throw R glows; the stick’s press arrow rotates.
- **Two emphasised**: A charge placed: Detonate L and Aim Underfoot on the d-pad both glow.
- **Four prompts**: Grabbing: the face cluster’s top and bottom, the right stick and Cancel B.
- **Riding**: A trigger, a shoulder, the left stick pulled down and A.
- **Empty**: A context with no prompts: nothing is drawn but the chips.
- **Row**: `layout="row"`: the menu’s Sort, Back and Select along the bottom, as at the foot of a game menu.
- **Bare**: `bare`: the list alone at `--prompt-size`, without the room around it or the chips, to lay over a game.
- **Light**: `colorScheme="light"`: the plates keep their dark fill, with a soft shadow on the page; the chips are light.
- **Dark**: `colorScheme="dark"`: the plates take a faint light edge so they part from a dark page; the chips turn dark.
## How it works
- Each context is a set of prompts: a verb and a button. A prompt’s id is its label and button unless given, so a prompt present in both the old and the new set (Cancel B, say) is the same row and stays on screen.
- On a swap, before the browser paints, every row is measured. Leavers are taken out of the flow where they stood (pinned to the list’s foot and right edge) and slide 0.6 em right as they fade in 170 ms, 30 ms apart. Rows that stay glide from their old place to their new one by FLIP with the Web Animations API. Newcomers slide 0.9 em in from the right with an overshoot, 55 ms apart from the top, starting 150 ms in so they never cross the leavers, and each glyph pops in from half its size 60 ms after its verb.
- The glyphs are small SVGs drawn in px of a 27 px verb and sized in em, so a prompt scales as one: a 32 px face disc, a 36 × 28 shoulder key with its outer corner cut, a trigger whose top slopes outwards, a d-pad marking its direction with a dark square, the four face buttons as rings with the one meant filled and pointing, and a stick seen slightly from above with a press or a direction arrow cut out of it by a mask.
- An emphasised prompt (an action to notice: a charge to detonate, a thing to throw) gets a warm rim on its plate and a soft box-shadow light behind it, with a faint glow on the verb; it flares once as it arrives, then breathes every 1.8 s. No filter touches the glyphs or the verb, so they stay sharp at any pixel density.
- Pressing a prompt remounts its glyph and verb, which replays their animations: the glyph dips to 0.82 and springs past 1, a ring expands and fades, the verb flashes brighter. A prompt with a next context moves there 220 ms later, so the press is seen before the set leaves.
- Uncontrolled, it keeps its own context, with a row of context chips under the prompts, and a demo plays a short run of play (climb, carry, place a charge, ride, open a menu) while it is on screen and untouched; any input hands it to the reader. Given context, it shows that set and asks onContextChange to move.
- There is no game behind the prompts here, so each sits on its own dark plate with round ends, as a HUD’s banners do, and the glyphs and verbs keep their colours on any page. The plate’s edge, its shadow and the chips follow the colour scheme through light-dark() tokens. The list sits in a room kept for four prompts, pinned to its foot with its right edge a little right of centre, so sets of any size sit about the middle without jumping sideways. bare draws the list alone, sized by --prompt-size.
## API reference
- **sets** (`ActionSet[]`, default `roam, climb, carry, charge, grab, ride, menu`): The contexts, each { id, label, prompts }. A prompt is { label, button, emphasis?, next?, id? }: button is A, B, X, Y, +, -, L, R, ZL, ZR, dpad(-up/-down/-left/-right), face-up/down/left/right, or a stick: ls, rs, with -press, -up or -down.
- **context** (`string`): The context shown, controlled: changing it swaps the set. The demo is off, and the context chips ask onContextChange.
- **defaultContext** (`string`, default `'climb'`): Uncontrolled, the context it starts in.
- **onContextChange** (`(context: string) => void`): Asked to change context: a pressed prompt’s next, or a context chip.
- **onAction** (`(prompt: ActionPrompt, context: string) => void`): Called when a prompt is pressed, by click, tap, Enter or its letter.
- **layout** (`'column' | 'row'`, default `'column'`): A column lined up on the right, as in play, or a row, as at the foot of a menu.
- **bare** (`boolean`, default `false`): The list alone, without the room kept around it and the context chips, to lay over a game of your own. Their type is 27 px, or --prompt-size.
- **autoplay** (`boolean`, default `true`): While on screen and untouched, a short run of play: contexts change and prompts are pressed. Uncontrolled only.
- **colorScheme** (`'light' | 'dark' | 'system'`): Forces light or dark for the plates’ edge and shadow and the chips; by default it follows the page. The glyphs and verbs keep their colours.
- **className** (`string`): Added to the root.
## Accessibility
- Every prompt is a real button named by its verb and button (“Jump, X button”, “Rotate, Right stick, press”); the glyph art is aria-hidden.
- While the component has focus, the letters A, B, X, Y, L and R press the prompt on that button, as a controller would; each prompt says its key with aria-keyshortcuts.
- A polite live region reads a new set (“Climb: Jump, X button. Let go, B button.”) and the verb of a pressed prompt.
- Leaving prompts are hidden from assistive technology and taken out of the tab order at once; if the focus was on one, it moves to the new set’s first prompt, or to the list.
- The context chips are toggle buttons (aria-pressed) in a labelled group; everything shows a :focus-visible ring.
- Reduced motion: no slides, pops, dips, rings or breathing; sets crossfade and the glow is still. The demo never plays.
## Source
### action-prompts/action-prompts.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import {
useCallback,
useEffect,
useEffectEvent,
useLayoutEffect,
useRef,
useState,
type CSSProperties,
type KeyboardEvent,
} from 'react';
import { Glyph, buttonName, glyphShape, type PromptButton } from './glyphs';
import { useAutoplay } from './use-autoplay';
import styles from './action-prompts.module.css';
/*
* Action prompts: the corner of a game HUD that says what the buttons do right now. The controls
* are context-sensitive (the same B is Back in a menu, Let go on a wall, Cancel while aiming), so
* each context brings its own set: a verb, then the button in the controller's shape.
*
* - A set swaps by prompt. Prompts that stay valid in the new context (Cancel B, say) stay and
* glide to their new place (measured before and after, then played back from the old place:
* FLIP). The others leave: they are taken out of the flow where they stood and slide right as
* they fade, 30 ms apart. The newcomers slide in from the right with a little overshoot, 55 ms
* apart from the top, each glyph popping in just after its verb.
* - An emphasised prompt (a new or time-sensitive action: a charge to detonate, a thing to throw)
* glows. It flares once as it arrives, then breathes.
* - Every prompt is a real button. Pressing it (a click, a tap, Enter, or the button's own letter
* while the component has focus: A, B, X, Y, L, R) dips the glyph in and springs it back with a
* ring of light, brightens the verb, calls `onAction`, and, uncontrolled, follows the prompt's
* `next` context a beat later, so the press is seen before the set leaves.
* - Uncontrolled, it keeps its own context, with a row of context chips under the prompts, and a
* demo plays a short run of play while it is on screen and untouched (climb, carry, place a
* charge, ride, open a menu). Given `context`, it shows that set; `onContextChange` asks to
* change it.
* - The prompts stand alone, centred: each sits on its own dark plate, as a HUD's banners do, so
* it reads on a light page or a dark one. `bare` draws the list alone, without the room kept
* for four prompts and without the chips, to lay over a game.
*/
export type { PromptButton };
export type ActionPrompt = {
/** Stable id within the sets; defaults to the label and button. Same id in two sets = stays. */
id?: string;
/** The verb, as shown. */
label: string;
/** Which button, drawn in its controller shape. */
button: PromptButton;
/** Glows: a new or time-sensitive action the player should notice. */
emphasis?: boolean;
/** The context to go to once it is pressed (uncontrolled), or null for none. */
next?: string | null;
};
export type ActionSet = {
/** The context's id. */
id: string;
/** Its name, for the stage's context buttons and for screen readers. */
label: string;
prompts: ActionPrompt[];
};
export const DEFAULT_SETS: ActionSet[] = [
{ id: 'roam', label: 'Roam', prompts: [] },
{
id: 'climb',
label: 'Climb',
prompts: [
{ label: 'Jump', button: 'X' },
{ label: 'Let go', button: 'B', next: 'roam' },
],
},
{
id: 'carry',
label: 'Carry',
prompts: [
{ label: 'Throw', button: 'R', emphasis: true, next: 'roam' },
{ label: 'Rotate', button: 'rs-press' },
{ label: 'Cancel', button: 'B', next: 'roam' },
],
},
{
id: 'charge',
label: 'Charge',
prompts: [
{ label: 'Detonate', button: 'L', emphasis: true, next: 'roam' },
{ label: 'Aim Underfoot', button: 'dpad-down', emphasis: true },
{ label: 'Cancel', button: 'B', next: 'roam' },
],
},
{
id: 'grab',
label: 'Grab',
prompts: [
{ label: 'Push', button: 'face-up' },
{ label: 'Pull', button: 'face-down' },
{ label: 'Move', button: 'rs' },
{ label: 'Cancel', button: 'B', next: 'roam' },
],
},
{
id: 'ride',
label: 'Ride',
prompts: [
{ label: 'Reset Camera', button: 'ZL' },
{ label: 'Soothe', button: 'L' },
{ label: 'Woah...', button: 'ls-down' },
{ label: 'Yah!', button: 'A' },
],
},
{
id: 'menu',
label: 'Menu',
prompts: [
{ label: 'Sort', button: 'Y' },
{ label: 'Back', button: 'B', next: 'roam' },
{ label: 'Select', button: 'A' },
],
},
];
type Phase = 'in' | 'stay' | 'out';
type Row = {
key: string;
prompt: ActionPrompt;
phase: Phase;
/** Its place in the entering order, for the stagger. */
order: number;
/** Where a leaving row stood, in px from the list's top and right. */
at?: { top: number; right: number; bottom: number };
/** Which swap it is leaving in. */
round?: number;
};
const keyOf = (prompt: ActionPrompt) => prompt.id ?? `${prompt.label}|${prompt.button}`;
/** How long leaving rows take, the stagger between them, and the delay before newcomers. */
const LEAVE = 170;
const LEAVE_STAGGER = 30;
/** How long after a press its `next` context comes in. */
const NEXT_AFTER = 220;
/** Keyboard letters that press a prompt's button. */
const KEYS: Record = {
a: ['A'],
b: ['B'],
x: ['X'],
y: ['Y'],
l: ['L', 'ZL'],
r: ['R', 'ZR'],
};
const shortcut = (button: PromptButton) =>
Object.entries(KEYS)
.find(([, buttons]) => buttons.includes(button))?.[0]
.toUpperCase();
/** The demo: a short run of play, as steps at ms from its start. */
const DEMO: ({ at: number } & ({ context: string } | { press: string }))[] = [
{ at: 0, context: 'roam' },
{ at: 700, context: 'climb' },
{ at: 2300, press: 'Jump|X' },
{ at: 3500, press: 'Let go|B' },
{ at: 4600, context: 'carry' },
{ at: 6600, press: 'Throw|R' },
{ at: 7800, context: 'charge' },
{ at: 9900, press: 'Detonate|L' },
{ at: 11000, context: 'ride' },
{ at: 12500, press: 'Yah!|A' },
{ at: 13100, press: 'Yah!|A' },
{ at: 14300, press: 'Woah...|ls-down' },
{ at: 15400, context: 'menu' },
{ at: 16800, press: 'Select|A' },
{ at: 17900, press: 'Back|B' },
];
const DEMO_LENGTH = 19400;
export type ActionPromptsProps = {
className?: string;
/** The contexts and their prompts. */
sets?: ActionSet[];
/** The context shown (controlled). */
context?: string;
/** The context it starts in, uncontrolled. */
defaultContext?: string;
/** Asked when a prompt with `next` is pressed, or a context chip. */
onContextChange?: (context: string) => void;
/** Called when a prompt is pressed, with the prompt and its context. */
onAction?: (prompt: ActionPrompt, context: string) => void;
/** A column at the lower right (as in play), or a row (as at the foot of a menu). */
layout?: 'column' | 'row';
/** The list alone, without the room kept around it and the context chips. */
bare?: boolean;
/** Plays a short run of play while on screen and untouched (uncontrolled only). */
autoplay?: boolean;
colorScheme?: 'light' | 'dark' | 'system';
};
export function ActionPrompts({
className,
sets = DEFAULT_SETS,
context: contextProp,
defaultContext = 'climb',
onContextChange,
onAction,
layout = 'column',
bare = false,
autoplay = true,
colorScheme,
}: ActionPromptsProps) {
const controlled = contextProp !== undefined;
const [ownContext, setOwnContext] = useState(defaultContext);
const context = controlled ? contextProp : ownContext;
const set = sets.find((item) => item.id === context);
const prompts = set?.prompts ?? [];
const { ref, take, playing } = useAutoplay();
const demo = playing && autoplay && !controlled;
const listRef = useRef(null);
const rowRefs = useRef(new Map());
const before = useRef(new Map());
const [rows, setRows] = useState(() =>
prompts.map((prompt, order) => ({ key: keyOf(prompt), prompt, phase: 'stay', order })),
);
const [presses, setPresses] = useState>({});
const [said, setSaid] = useState('');
const timers = useRef([]);
const later = useCallback((ms: number, fn: () => void) => {
timers.current.push(window.setTimeout(fn, ms));
}, []);
useEffect(() => () => timers.current.forEach((id) => window.clearTimeout(id)), []);
const goTo = useCallback(
(next: string) => {
if (!controlled) setOwnContext(next);
onContextChange?.(next);
},
[controlled, onContextChange],
);
// A new set: measure the old layout, mark leavers where they stand, and let the rest flow.
const promptsKey =
prompts.map(keyOf).join('\n') + '\n' + prompts.map((p) => +!!p.emphasis).join('');
const lastKey = useRef(promptsKey);
const rounds = useRef(0);
const refocus = useRef(false);
useLayoutEffect(() => {
if (lastKey.current === promptsKey) return;
lastKey.current = promptsKey;
const list = listRef.current;
const box = list?.getBoundingClientRect();
before.current.clear();
const round = ++rounds.current;
// If the focus is on a prompt that is leaving, it moves to the new set (or the list) after.
const focused = listRef.current?.querySelector('li:has(:focus)');
const focusedKey = [...rowRefs.current].find(([, element]) => element === focused)?.[0];
refocus.current = focusedKey !== undefined && !prompts.some((p) => keyOf(p) === focusedKey);
const rects = new Map();
for (const [key, element] of rowRefs.current) rects.set(key, element.getBoundingClientRect());
const wanted = new Map(prompts.map((prompt) => [keyOf(prompt), prompt]));
setRows((old) => {
const leaving: Row[] = [];
for (const row of old) {
if (wanted.has(row.key) || row.phase === 'out') {
if (row.phase === 'out') leaving.push(row);
continue;
}
const rect = rects.get(row.key);
leaving.push({
...row,
phase: 'out',
round,
order: leaving.length,
at:
rect && box
? {
top: rect.top - box.top,
right: box.right - rect.right,
bottom: box.bottom - rect.bottom,
}
: undefined,
});
}
const kept = new Set(old.filter((row) => row.phase !== 'out').map((row) => row.key));
let entering = 0;
const fresh = prompts.map((prompt): Row => {
const key = keyOf(prompt);
if (kept.has(key)) {
const rect = rects.get(key);
if (rect) before.current.set(key, rect);
return { key, prompt, phase: 'stay', order: 0 };
}
return { key, prompt, phase: 'in', order: entering++ };
});
return [...fresh, ...leaving];
});
// A safety net: leavers drop out on their animation's end, or after this at the latest.
later(LEAVE + LEAVE_STAGGER * 8 + 240, () =>
setRows((now) => now.filter((row) => row.phase !== 'out' || (row.round ?? 0) !== round)),
);
setSaid(
prompts.length
? `${set?.label ?? context}: ${prompts.map((p) => `${p.label}, ${buttonName(p.button)}`).join('. ')}.`
: '',
);
}, [promptsKey]);
// Remove leavers once they are gone (each out row schedules its own removal on mount).
const dropOut = useCallback((key: string) => {
setRows((now) => now.filter((row) => !(row.key === key && row.phase === 'out')));
}, []);
// FLIP: rows that stayed play from where they were to where they are.
useLayoutEffect(() => {
if (!before.current.size) return;
const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
for (const [key, rect] of before.current) {
const element = rowRefs.current.get(key);
if (!element || reduced) continue;
const now = element.getBoundingClientRect();
const dx = rect.left - now.left;
const dy = rect.top - now.top;
if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5) continue;
element.animate([{ translate: `${dx}px ${dy}px` }, { translate: '0 0' }], {
duration: 340,
easing: 'cubic-bezier(0.2, 0.9, 0.25, 1.05)',
});
}
before.current.clear();
}, [rows]);
useEffect(() => {
if (!refocus.current) return;
refocus.current = false;
const next = listRef.current?.querySelector(
'li:not([data-phase="out"]) button',
);
(next ?? listRef.current)?.focus({ preventScroll: true });
}, [rows]);
const press = useCallback(
(key: string) => {
const row = rows.find((item) => item.key === key && item.phase !== 'out');
if (!row) return;
setPresses((now) => ({ ...now, [key]: (now[key] ?? 0) + 1 }));
setSaid(row.prompt.label);
onAction?.(row.prompt, context);
const next = row.prompt.next;
if (next != null) later(NEXT_AFTER, () => goTo(next));
},
[rows, onAction, context, later, goTo],
);
// 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 ('context' in item) setOwnContext(item.context);
else press(item.press);
});
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((id) => window.clearTimeout(id));
}, [demo]);
const onKeyDown = (event: KeyboardEvent) => {
if (!controlled) take();
if (event.altKey || event.ctrlKey || event.metaKey) return;
const buttons = KEYS[event.key.toLowerCase()];
if (!buttons) return;
const row = rows.find((item) => item.phase !== 'out' && buttons.includes(item.prompt.button));
if (!row) return;
event.preventDefault();
press(row.key);
};
return (
{rows.map((row) => {
const count = presses[row.key] ?? 0;
const out = row.phase === 'out';
const style = {
'--i': row.order,
// A leaver stays where it stood, from the corner the list is pinned to (on the stage it
// is pinned to the foot of its room; bare, it flows from the top and lines up right).
...(out && row.at
? bare
? { position: 'absolute', top: row.at.top, right: row.at.right }
: { position: 'absolute', bottom: row.at.bottom, right: row.at.right }
: null),
} as unknown as CSSProperties;
return (