# Controller glyphs
> Every controller input a game names in its prompts, as one reusable glyph that dips, lights and teaches.
The badges a game uses to say which input to use: face buttons, plus and minus, shoulder tabs, the d-pad, the direction buttons and both sticks with arrows for tilt, press and rotate, alone or with words beside them. Each is one Glyph with sizes, a press that dips and springs back with a flash, a glow, and looping hints. Press them, play the sheet with the keyboard or a gamepad, or watch a short run of play.
A React component by Bruno Delorence: https://brunodelorence.com/components/controller-glyphs. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: Games · Controls.
## Anatomy
1. **Face badge**: A round tan badge 32 units across in a 40-unit box, the letter cut out of it by a mask. Plus and minus are smaller badges with the sign cut out.
2. **Prompt words**: `label` beside the glyph, 0.6 of its size, semibold in a warm white on a dark pill of its own; `labelPosition` puts it left, right or below.
3. **Shoulder tab**: L and R are tabs slanted on their outer side; ZL and ZR are triggers whose top rises to the outer corner. The right ones are mirror images.
4. **Edge**: The same shape again behind the tan, filled and stroked near-black 1.2 units out all round: a crisp dark outline that shows through the cut letters, keeps a glow out of them, and makes the glyph read on a light stage and a dark one.
5. **D-pad cross**: A cross with arms of 10.5 units; `direction` cuts a square out of the arm it names.
6. **Stick cap**: The stick seen from the side: an oval cap with a rim and a thin groove, its letter (L or R) cut out. When pressed it leans the way it is pushed.
7. **Foot**: The short stem under the cap; arrows that cross it are cut around it.
8. **Arrow**: How to move the stick, set by `motion`: tilt arrows beside it, a press arrow on top, up and down arrows, or two swinging rotate arrows. The box widens to hold them.
## When to use
- Telling a player which input does what, in a prompt over the game: “A Jump”, “ZL Aim”, “press the left stick to crouch”.
- A tutorial that teaches a move: a stick glyph with its arrows (tilt, press, rotate) and `animate` looping the hint until it is done.
- Showing that an input was taken: `pressed` dips the glyph and flashes it while the button is held, `lit` keeps it glowing.
- A controls screen, a pause menu or a help sheet that lists every input of a pad in one consistent drawing.
- Prompts drawn over anything: every shape carries its own dark edge and every label its own dark plate, so they read on sky, snow, a white menu or a black one.
## When not to use
- Keyboard shortcuts in an app or on a website. Use key caps (a kbd element) with the platform’s own keys.
- Clickable actions in a web UI. Use a button with words; a glyph alone names an input, it is not a control.
- Another pad’s own buttons (a cross, circle, square and triangle layout). These glyphs draw one family of pad; draw that pad’s set instead.
- A whole action bar with cooldowns and charges. Use a quick selector or ability icons and put a small glyph on each slot.
- Inside running text at body size. Under about 20 px the edge and the arrows close up; set the input in words, or use the glyph at sm or larger beside the line.
## Installation
Install it with the shadcn CLI, into components/controller-glyphs of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/controller-glyphs.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 { Glyph } from './controller-glyphs';
export function InteractPrompt({ held }: { held: boolean }) {
return (
);
}
```
## States
- **At rest**: The face buttons and plus and minus, tan inside their dark edge: what a prompt shows by default.
- **Pressed**: `pressed`: dipped to 0.86 with a flash of light. A pressed stick does not dip; its cap leans the way of its motion, or `lean`.
- **Lit**: `lit`: a glow behind the glyph and its words, for the input the game wants noticed: a warm white on a dark stage, amber on a light one, so it shows on both.
- **Hint looping**: `animate`: tilt arrows nudge out, the press arrow bobs into the cap, a face button breathes. It loops by design, and stops under reduced motion.
- **Stick motions**: One stick, every `motion`: none, right, left, either way, press, down, up, up or down, rotate.
- **Directions**: The d-pad and the four direction buttons, plain and with one `direction` marked (or `all` buttons filled).
- **Prompts**: `label` with `labelPosition` left, right and below, as a game lays its prompts out.
- **Sizes**: `size` sm 24, md 32, lg 40 (the kit’s own) and xl 56; any number of px works too.
- **Sheet, light**: `ControllerGlyphs` with `autoplay={false}` and `colorScheme="light"`: every glyph in groups on a white stage, the last input at the foot.
- **Sheet, dark**: `colorScheme="dark"`: only the stage and its captions turn dark; the glyphs keep their tan and their edge, as a game’s prompts do.
## How it works
- Every glyph is an SVG on one grid, where a face button’s box is 40 units: a round badge of 32 (27 for plus and minus), a tab slanted on its outer side, a trigger whose top rises to the outer corner, a cross of 32.5 with arms of 10.5, four direction buttons of 10.5 in a diamond, and a stick drawn from the side, an oval cap with a rim and a thin groove on a short foot.
- Letters and marks are not painted: an SVG mask cuts them out of the tan shape, over a dark edge drawn behind (the same shape filled and stroked near-black 1.2 units out all round), so every glyph carries its own crisp outline and reads on a light stage and a dark one alike. Arrows laid over a stick are cut around in the same way, so a press arrow sits in a notch of the cap.
- The SVG is sized in em of --glyph-size, the box of a face button, so size sets one number: sm 24, md 32, lg 40 (the kit’s own), xl 56 or any px; a label beside, before or under it is 0.6 of it, semibold, on a dark pill of its own.
- pressed dips the glyph to 0.86 in 70 ms and springs it back over 340 ms with an overshoot (a cubic-bezier past 1); a ring of light opens and fades behind it on each press. A pushed stick’s cap leans 2.6 units the way it goes, or sinks when pressed in, and its arrows nudge out.
- lit adds a glow behind the sharp shapes (two drop-shadows), warm white on a dark stage and amber on a light one; the opaque edge keeps it out of the cut letters. animate loops the hint: tilt arrows nudge out, the press arrow bobs into a squashed cap, the rotate arrows swing, a marked direction blinks.
- On the sheet, inputs are ids (A, dpad-up, LS-left…) and one input presses every glyph that names it: the plain stick, its tilt and its either-way glyphs, and a prompt. Pointer, Enter and Space press a glyph while held; with focus on the sheet the keyboard plays a pad (A B X Y, Q E, 1 3, + −, arrows, Shift + arrows); a gamepad is read each frame once it shows up.
- A demo plays a short run of play while it is on screen and untouched (walk, jump, aim and throw, quick items, crouch, look around, menu), with the last input as a prompt at the foot; any input hands it to the reader. The stage is plain, white or near-black through light-dark() tokens; the glyphs keep their colours on both.
## API reference
- **size** (`'sm' | 'md' | 'lg' | 'xl' | number`): On both. Glyph: the box of a face button in px, sm 24, md 32, lg 40 (the kit’s), xl 56; without it, --glyph-size (40 px). ControllerGlyphs: the size of every glyph on the sheet, by default 48 px on a wide stage, 40 under 760 px, then 32 and 26.
- **gamepad** (`boolean`, default `true`): ControllerGlyphs: reads a connected gamepad (it shows up after its first press), each frame while the sheet is on screen.
- **onInput** (`(input: string) => void`): ControllerGlyphs: called with each input the reader presses ('A', 'dpad-up', 'LS-left'…).
- **autoplay** (`boolean`, default `true`): ControllerGlyphs: while on screen and untouched, a short run of play on the sheet.
- **colorScheme** (`'light' | 'dark' | 'system'`): ControllerGlyphs: the stage’s colours, light, dark or the reader’s system setting. Without it the component follows the page’s color-scheme.
- **className** (`string`): Extra class for the root (on both components).
- **name** (`'A' | 'B' | 'X' | 'Y' | 'plus' | 'minus' | 'L' | 'R' | 'ZL' | 'ZR' | 'dpad' | 'buttons' | 'LS' | 'RS'`): Glyph: which input it names. Required.
- **direction** (`'up' | 'down' | 'left' | 'right' | 'all'`): Glyph: for the d-pad and the direction buttons, the one to mark (or all buttons).
- **motion** (`'none' | 'left' | 'right' | 'horizontal' | 'press' | 'up' | 'down' | 'vertical' | 'rotate'`, default `'none'`): Glyph: for a stick, the arrows that say how to move it.
- **pressed** (`boolean`, default `false`): Glyph: held down; it dips and lights, and springs back when released.
- **lean** (`'up' | 'down' | 'left' | 'right'`): Glyph: the way a pressed stick’s cap leans; by default its motion’s.
- **lit** (`boolean`, default `false`): Glyph: glowing, for the input the game wants noticed.
- **animate** (`boolean`, default `false`): Glyph: loops its hint (arrows nudge, the press arrow bobs, a marked direction blinks).
- **label** (`ReactNode`): Glyph: words beside it, as in a prompt.
- **labelPosition** (`'left' | 'right' | 'below'`, default `'right'`): Glyph: where the words go.
- **title** (`string`): Glyph: its accessible name; by default “A button”, “Left stick, tilt left”…
## Accessibility
- Each glyph is an image with a spoken name (“A button”, “D-pad up”, “Right stick, rotate”); its SVG is hidden, and a label beside it is real text.
- On the sheet, every glyph is a button in a named group per section, reached with Tab, pressed with Enter or Space while held, with a visible focus ring; a focused or hovered glyph loops its hint.
- The keyboard plays the pad only while focus is on the sheet, so the page’s own keys are never taken; the keys are listed in How it works.
- A polite live region says each input the reader presses and its action (“A button, Jump”), never the demo’s.
- Under reduced motion presses and leans change at once, nothing loops, flashes or blinks, and the demo never plays.
## Source
### controller-glyphs/controller-glyphs.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import {
useCallback,
useEffect,
useEffectEvent,
useState,
type KeyboardEvent,
type PointerEvent,
} from 'react';
import {
Glyph,
describeGlyph,
type GlyphDirection,
type GlyphName,
type GlyphSize,
type StickMotion,
} from './glyph';
import { useAutoplay } from './use-autoplay';
import styles from './controller-glyphs.module.css';
/*
* Controller glyphs: the full set of controller inputs a game names in its prompts, laid out as
* a sheet on a plain stage, every glyph live. Each glyph carries its own dark edge and each label
* its own dark plate, so the sheet reads on a light stage and a dark one with no scene behind it.
*
* - The glyphs are (glyph.tsx), exported to use alone: face buttons, plus and minus,
* shoulder tabs, the d-pad, the direction buttons, both sticks with their arrows, and prompts
* with words beside them.
* - Inputs are ids ('A', 'dpad-up', 'LS-left'...). One press lights every glyph on the sheet
* that names it: pushing the left stick left dips the plain stick (its cap leaning left), the
* "tilt left" and the "tilt left or right" glyphs, and a prompt that uses it.
* - The reader presses glyphs with the pointer, or Enter and Space on a focused one; with focus
* on the sheet, the keyboard plays a pad (A B X Y, Q E for L R, 1 3 for ZL ZR, + and −, arrows
* for the d-pad, Shift + arrows for the left stick); a gamepad, once it wakes up with a press,
* is read each frame while the sheet is on screen.
* - The last input shows at the foot as a prompt, with the action it does in the demo's game.
* - While on screen and untouched, a demo plays a short run of play: walk, jump, aim and throw,
* a quick item, crouch, look around, open the menu.
*/
type Item = {
id: string;
name: GlyphName;
direction?: GlyphDirection | 'all';
motion?: StickMotion;
};
const STICK_MOTIONS: StickMotion[] = [
'none',
'right',
'left',
'horizontal',
'press',
'down',
'up',
'vertical',
'rotate',
];
const DIRS: GlyphDirection[] = ['up', 'down', 'left', 'right'];
const GROUPS: { title: string; wide?: boolean; items: Item[] }[] = [
{
title: 'Face buttons',
items: (['A', 'B', 'X', 'Y', 'plus', 'minus'] as GlyphName[]).map((name) => ({
id: name,
name,
})),
},
{
title: 'Shoulders',
items: (['L', 'R', 'ZL', 'ZR'] as GlyphName[]).map((name) => ({ id: name, name })),
},
{
title: 'Directions',
wide: true,
items: [
{ id: 'buttons-all', name: 'buttons', direction: 'all' },
...DIRS.map((d): Item => ({ id: `buttons-${d}`, name: 'buttons', direction: d })),
{ id: 'dpad-none', name: 'dpad' },
...DIRS.map((d): Item => ({ id: `dpad-${d}`, name: 'dpad', direction: d })),
],
},
...(['RS', 'LS'] as const).map((stick) => ({
title: stick === 'RS' ? 'Right stick' : 'Left stick',
wide: true,
items: STICK_MOTIONS.map((motion): Item => ({ id: `${stick}-${motion}`, name: stick, motion })),
})),
];
/** The prompts row: a glyph with words, as the game shows them. */
const PROMPTS: (Item & { label: string; position: 'left' | 'right' | 'below' })[] = [
{ id: 'prompt-A', name: 'A', label: 'Jump', position: 'left' },
{ id: 'prompt-ZL', name: 'ZL', label: 'Aim', position: 'right' },
{ id: 'prompt-ZR', name: 'ZR', label: 'Throw', position: 'below' },
{ id: 'prompt-LS', name: 'LS', motion: 'press', label: 'Crouch', position: 'left' },
];
/** What each input does in the demo's game, for the readout at the foot. */
const ACTIONS: Record = {
A: 'Jump',
B: 'Cancel',
X: 'Climb',
Y: 'Sort',
plus: 'Menu',
minus: 'Map',
L: 'Ability',
R: 'Throw',
ZL: 'Aim',
ZR: 'Throw',
'dpad-up': 'Quick item',
'dpad-down': 'Whistle',
'dpad-left': 'Shield',
'dpad-right': 'Weapon',
'LS-left': 'Walk',
'LS-right': 'Walk',
'LS-up': 'Walk',
'LS-down': 'Walk',
'LS-press': 'Crouch',
'RS-left': 'Look',
'RS-right': 'Look',
'RS-up': 'Look',
'RS-down': 'Look',
'RS-press': 'Zoom',
'RS-rotate': 'Look around',
};
/** An input, and the ids of every glyph on the sheet that names it. */
function targets(input: string): string[] {
const [head, tail] = input.split('-');
if (head === 'dpad' && tail)
return [`dpad-${tail}`, `buttons-${tail}`, 'dpad-none', 'buttons-all'];
if ((head === 'LS' || head === 'RS') && tail) {
const pair =
tail === 'left' || tail === 'right'
? 'horizontal'
: tail === 'up' || tail === 'down'
? 'vertical'
: undefined;
return [
`${head}-none`,
`${head}-${tail}`,
...(pair ? [`${head}-${pair}`] : []),
...PROMPTS.filter((p) => p.name === head && p.motion === tail).map((p) => p.id),
];
}
return [input, ...PROMPTS.filter((p) => p.name === input && !p.motion).map((p) => p.id)];
}
/** The input a glyph of the sheet presses: a stick's "left or right" tilts it right, the
* direction buttons are the d-pad's, a prompt presses its glyph's. */
function inputOf(item: Item): string {
if (item.id.startsWith('prompt-')) return item.motion ? `${item.name}-${item.motion}` : item.name;
if (item.name === 'buttons' && item.direction !== 'all') return `dpad-${item.direction}`;
if (item.motion === 'horizontal') return `${item.name}-right`;
if (item.motion === 'vertical') return `${item.name}-up`;
return item.id;
}
/** The glyph of an input, for the readout. */
function glyphOf(input: string): Item {
const [head, tail] = input.split('-');
if (head === 'dpad') return { id: input, name: 'dpad', direction: tail as GlyphDirection };
if (head === 'LS' || head === 'RS') return { id: input, name: head, motion: tail as StickMotion };
return { id: input, name: head as GlyphName };
}
/** A run of play, as inputs held from `at` for `hold` ms. */
const DEMO: { at: number; input: string; hold: number }[] = [
{ at: 300, input: 'LS-right', hold: 1300 },
{ at: 1800, input: 'A', hold: 200 },
{ at: 2500, input: 'ZL', hold: 2300 },
{ at: 2900, input: 'RS-left', hold: 500 },
{ at: 3600, input: 'RS-right', hold: 450 },
{ at: 4300, input: 'ZR', hold: 220 },
{ at: 5300, input: 'dpad-up', hold: 220 },
{ at: 5900, input: 'dpad-right', hold: 220 },
{ at: 6600, input: 'LS-press', hold: 600 },
{ at: 7500, input: 'RS-rotate', hold: 1300 },
{ at: 9100, input: 'B', hold: 200 },
{ at: 9700, input: 'X', hold: 200 },
{ at: 10400, input: 'plus', hold: 260 },
];
const DEMO_LENGTH = 12000;
/** The keyboard as a pad, while focus is on the sheet. */
function keyInput(event: { code: string; key: string; shiftKey: boolean }): string | undefined {
const arrow = event.code.startsWith('Arrow') ? event.code.slice(5).toLowerCase() : undefined;
if (arrow) return event.shiftKey ? `LS-${arrow}` : `dpad-${arrow}`;
const keys: Record = {
KeyA: 'A',
KeyB: 'B',
KeyX: 'X',
KeyY: 'Y',
KeyQ: 'L',
KeyE: 'R',
Digit1: 'ZL',
Digit3: 'ZR',
Minus: 'minus',
NumpadSubtract: 'minus',
Equal: 'plus',
NumpadAdd: 'plus',
};
return keys[event.code];
}
/** A standard-mapping gamepad as inputs: its face buttons by position (right A, bottom B...). */
function padInputs(pad: Gamepad): string[] {
const on: string[] = [];
const names = ['B', 'A', 'Y', 'X', 'L', 'R', 'ZL', 'ZR', 'minus', 'plus', 'LS-press', 'RS-press'];
names.forEach((name, index) => pad.buttons[index]?.pressed && on.push(name));
(['up', 'down', 'left', 'right'] as const).forEach(
(d, index) => pad.buttons[12 + index]?.pressed && on.push(`dpad-${d}`),
);
const stick = (prefix: string, x = 0, y = 0) => {
if (Math.hypot(x, y) < 0.45) return;
on.push(
Math.abs(x) > Math.abs(y)
? `${prefix}-${x > 0 ? 'right' : 'left'}`
: `${prefix}-${y > 0 ? 'down' : 'up'}`,
);
};
stick('LS', pad.axes[0], pad.axes[1]);
stick('RS', pad.axes[2], pad.axes[3]);
return on;
}
export function ControllerGlyphs({
size,
gamepad = true,
onInput,
autoplay = true,
colorScheme,
className = '',
}: {
/** The size of every glyph on the sheet; by default 48 px on a wide stage, 40 (the kit's), 32 or 26 on narrower ones. */
size?: GlyphSize;
/** Reads a connected gamepad (it shows up after its first press). */
gamepad?: boolean;
/** Called with each input the reader presses ('A', 'dpad-up', 'LS-left'...). */
onInput?: (input: string) => void;
/** While on screen and untouched, a short run of play on the sheet. */
autoplay?: boolean;
/** Light or dark stage, or the reader's ('system'); without it, the page's color-scheme. */
colorScheme?: 'light' | 'dark' | 'system';
className?: string;
}) {
const { ref: root, playing, visible, take } = useAutoplay(7000);
const demo = autoplay && playing;
/** The inputs held, by where they come from, so a key let go does not release the pad's. */
const [held, setHeld] = useState>({});
const [last, setLast] = useState('A');
const [message, setMessage] = useState('');
/** The key under the mouse or the keyboard's focus, which loops its hint. */
const [hint, setHint] = useState();
const hold = useCallback((source: string, inputs: string[]) => {
setHeld((now) => {
const before = now[source] ?? [];
if (before.length === inputs.length && before.every((input, i) => input === inputs[i]))
return now;
return { ...now, [source]: inputs };
});
}, []);
/** The reader pressed an input: it is theirs from now on, and it is announced. */
const press = useEffectEvent((source: string, input: string) => {
take();
hold(source, [input]);
setLast(input);
const item = glyphOf(input);
const action = ACTIONS[input];
setMessage(
`${describeGlyph(item.name, { direction: item.direction, motion: item.motion })}${action ? `, ${action}` : ''}`,
);
onInput?.(input);
});
const lit = new Set(Object.values(held).flat().flatMap(targets));
// The demo: inputs held and let go on a loop, while it may play.
useEffect(() => {
if (!demo) return;
let timers: number[] = [];
const run = () => {
timers = DEMO.flatMap(({ at, input, hold: ms }) => [
window.setTimeout(() => {
hold('demo', [input]);
setLast(input);
}, at),
window.setTimeout(() => hold('demo', []), at + ms),
]);
};
run();
const loop = window.setInterval(run, DEMO_LENGTH);
return () => {
timers.forEach((timer) => window.clearTimeout(timer));
window.clearInterval(loop);
hold('demo', []);
};
}, [demo, hold]);
// A gamepad, read each frame while the sheet is on screen and one is connected.
const [pads, setPads] = useState(0);
useEffect(() => {
if (!gamepad || typeof navigator === 'undefined' || !navigator.getGamepads) return;
const count = () => setPads(navigator.getGamepads().filter(Boolean).length);
window.addEventListener('gamepadconnected', count);
window.addEventListener('gamepaddisconnected', count);
return () => {
window.removeEventListener('gamepadconnected', count);
window.removeEventListener('gamepaddisconnected', count);
};
}, [gamepad]);
const readPad = useEffectEvent((inputs: string[]) => {
const before = held.pad ?? [];
const fresh = inputs.filter((input) => !before.includes(input));
if (fresh.length) press('pad', fresh[0]);
hold('pad', inputs);
});
useEffect(() => {
if (!gamepad || !pads || !visible) return;
let frame = 0;
const tick = () => {
const pad = navigator.getGamepads().find(Boolean);
readPad(pad ? padInputs(pad) : []);
frame = requestAnimationFrame(tick);
};
frame = requestAnimationFrame(tick);
return () => cancelAnimationFrame(frame);
}, [gamepad, pads, visible]);
const onKeyDown = (event: KeyboardEvent) => {
take();
if (event.metaKey || event.ctrlKey || event.altKey) return;
const input = keyInput(event);
if (!input) return;
event.preventDefault();
if (!event.repeat) press('keys', input);
};
const onKeyUp = (event: KeyboardEvent) => {
if (keyInput(event)) hold('keys', []);
};
/** A glyph on the sheet: a button that presses its own input while held. */
const key = (item: Item, label?: { text: string; position: 'left' | 'right' | 'below' }) => {
const input = inputOf(item);
const down = (event: PointerEvent) => {
if (event.button !== 0) return;
event.currentTarget.setPointerCapture?.(event.pointerId);
press('pointer', input);
};
const up = () => hold('pointer', []);
return (
);
};
const readout = glyphOf(last);
return (