# Mechanical Keyboard (`mechanical-keyboard`) > Full Mac keyboard with tactile depth-button keycaps — lifts on hover, snaps on press, plays synthesised mechanical click sounds. - **Docs:** https://www.mellowui.com/components/mechanical-keyboard - **Markdown:** https://www.mellowui.com/components/mechanical-keyboard.md - **Registry:** https://www.mellowui.com/r/mechanical-keyboard.json - **Tool prompt:** https://www.mellowui.com/api/prompt/mechanical-keyboard - **Categories:** interactive, 3d, audio - **Dependencies:** none ## AI prompt Add a MechanicalKeyboard component from the mellow library. It renders a full Mac keyboard where every key has a raised 3D face that lifts on hover and snaps down on press, with synthesised mechanical click sounds. Props: enableSound (bool, default true), showPreview (bool — floating keystroke labels above the board), variant ('default'|'rgb' — rgb is a backlit board with per-key rainbow underglow where each press fires a color ripple across neighbouring keys; theme-adaptive, dark caps in dark mode and white caps in light mode), keyDepth (px, default 3), onKeyPress (code: string) => void. Wrap in overflow-x:auto for mobile. ## Install ```bash npx shadcn@latest add https://mellowui.com/r/mechanical-keyboard.json ``` ## Props | Prop | Type | Default | Description | |---|---|---|---| | `enableSound` | `boolean` | `true` | Play WebAudio mechanical click sounds on press and release. | | `showPreview` | `boolean` | `false` | Float key-legend ghosts above the board as keys are pressed. | | `variant` | `"default" \| "rgb"` | `"default"` | default = themed ink glass. rgb = backlit board with per-key rainbow underglow — each press ripples color across neighbouring keys. Adapts to theme: dark caps in dark mode, white caps in light mode. | | `keyDepth` | `number` | `3` | Height of the raised keycap block in pixels. | | `onKeyPress` | `(code: string) => void` | — | Callback fired on each key press with the KeyboardEvent.code value. | | `className` | `string` | — | Additional CSS classes for the outer wrapper. | ## Design notes - Client component (`"use client"`) — required for animation and refs. - Uses Mellow design tokens: `--ink`, `--ink-rgb`, `--background`, `--background-rgb`, `--rule`, `--font-sans`, `--font-serif`, `--font-mono`. Tokens auto-flip between light and dark themes — never hardcode colors. - Respects `prefers-reduced-motion: reduce` where applicable. - Self-contained — no shared utilities. Copy-paste, not a package. ## Source ```tsx "use client"; import React, { useState, useRef, useEffect, useCallback } from "react"; type KeySoundType = "alpha" | "modifier" | "wide" | "fn"; type SoundPhase = "press" | "release"; type SoundRow = [number, number, number, number, number]; const SOUND_PARAMS: Record = { alpha: [[0.040, 7, 0.72, 2800, 0.56], [0.026, 11, 0.48, 5500, 0.40]], modifier: [[0.035, 8, 0.52, 2000, 0.44], [0.024, 12, 0.36, 4000, 0.30]], wide: [[0.060, 5, 0.85, 1000, 0.65], [0.040, 8, 0.60, 2000, 0.45]], fn: [[0.032, 8, 0.60, 3500, 0.48], [0.022, 12, 0.42, 6000, 0.32]], }; function playKeySound(ctx: AudioContext, phase: SoundPhase, type: KeySoundType) { const [dur, decay, amp, lpHz, gain] = SOUND_PARAMS[type][phase === "press" ? 0 : 1]; const len = Math.floor(ctx.sampleRate * dur); const buf = ctx.createBuffer(1, len, ctx.sampleRate); const data = buf.getChannelData(0); for (let i = 0; i < len; i++) { data[i] = (Math.random() * 2 - 1) * Math.pow(1 - i / len, decay) * amp; } const src = ctx.createBufferSource(); src.buffer = buf; const lp = ctx.createBiquadFilter(); lp.type = "lowpass"; lp.frequency.value = lpHz; const g = ctx.createGain(); g.gain.value = gain; src.connect(lp); lp.connect(g); g.connect(ctx.destination); src.start(); } interface KeyDef { code: string; label: string; sub?: string; w?: number; sound?: KeySoundType; } const KB_W = 680; const KEY_H = 42; const FN_H = 30; const GAP = 4; const ARROW_H = Math.floor((KEY_H - GAP) / 2); const FN_ROW: KeyDef[] = [ { code: "Escape", label: "esc", w: 1.5, sound: "modifier" }, { code: "F1", label: "F1", sound: "fn" }, { code: "F2", label: "F2", sound: "fn" }, { code: "F3", label: "F3", sound: "fn" }, { code: "F4", label: "F4", sound: "fn" }, { code: "F5", label: "F5", sound: "fn" }, { code: "F6", label: "F6", sound: "fn" }, { code: "F7", label: "F7", sound: "fn" }, { code: "F8", label: "F8", sound: "fn" }, { code: "F9", label: "F9", sound: "fn" }, { code: "F10", label: "F10", sound: "fn" }, { code: "F11", label: "F11", sound: "fn" }, { code: "F12", label: "F12", sound: "fn" }, ]; const MAIN_ROWS: KeyDef[][] = [ [ { code: "Backquote", label: "`", sub: "~" }, { code: "Digit1", label: "1", sub: "!" }, { code: "Digit2", label: "2", sub: "@" }, { code: "Digit3", label: "3", sub: "#" }, { code: "Digit4", label: "4", sub: "$" }, { code: "Digit5", label: "5", sub: "%" }, { code: "Digit6", label: "6", sub: "^" }, { code: "Digit7", label: "7", sub: "&" }, { code: "Digit8", label: "8", sub: "*" }, { code: "Digit9", label: "9", sub: "(" }, { code: "Digit0", label: "0", sub: ")" }, { code: "Minus", label: "-", sub: "_" }, { code: "Equal", label: "=", sub: "+" }, { code: "Backspace", label: "delete", w: 2, sound: "wide" }, ], [ { code: "Tab", label: "tab", w: 1.5, sound: "modifier" }, { code: "KeyQ", label: "Q" }, { code: "KeyW", label: "W" }, { code: "KeyE", label: "E" }, { code: "KeyR", label: "R" }, { code: "KeyT", label: "T" }, { code: "KeyY", label: "Y" }, { code: "KeyU", label: "U" }, { code: "KeyI", label: "I" }, { code: "KeyO", label: "O" }, { code: "KeyP", label: "P" }, { code: "BracketLeft", label: "[", sub: "{" }, { code: "BracketRight", label: "]", sub: "}" }, { code: "Backslash", label: "\\", sub: "|", w: 1.5 }, ], [ { code: "CapsLock", label: "caps", w: 1.75, sound: "modifier" }, { code: "KeyA", label: "A" }, { code: "KeyS", label: "S" }, { code: "KeyD", label: "D" }, { code: "KeyF", label: "F" }, { code: "KeyG", label: "G" }, { code: "KeyH", label: "H" }, { code: "KeyJ", label: "J" }, { code: "KeyK", label: "K" }, { code: "KeyL", label: "L" }, { code: "Semicolon", label: ";", sub: ":" }, { code: "Quote", label: "'", sub: '"' }, { code: "Enter", label: "return", w: 2.25, sound: "wide" }, ], [ { code: "ShiftLeft", label: "shift", w: 2.25, sound: "modifier" }, { code: "KeyZ", label: "Z" }, { code: "KeyX", label: "X" }, { code: "KeyC", label: "C" }, { code: "KeyV", label: "V" }, { code: "KeyB", label: "B" }, { code: "KeyN", label: "N" }, { code: "KeyM", label: "M" }, { code: "Comma", label: ",", sub: "<" }, { code: "Period", label: ".", sub: ">" }, { code: "Slash", label: "/", sub: "?" }, { code: "ShiftRight", label: "shift", w: 2.75, sound: "modifier" }, ], ]; const BOTTOM_ROW: KeyDef[] = [ { code: "Fn", label: "fn", w: 1.25, sound: "modifier" }, { code: "ControlLeft", label: "ctrl", w: 1.25, sound: "modifier" }, { code: "AltLeft", label: "opt", w: 1.25, sound: "modifier" }, { code: "MetaLeft", label: "cmd", w: 1.5, sound: "modifier" }, { code: "Space", label: "", w: 6.25, sound: "wide" }, { code: "MetaRight", label: "cmd", w: 1.5, sound: "modifier" }, { code: "AltRight", label: "opt", w: 1.25, sound: "modifier" }, ]; const ARROW_UP_DEF: KeyDef = { code: "ArrowUp", label: "↑", sound: "modifier" }; const ARROW_ROW_DEFS: KeyDef[] = [ { code: "ArrowLeft", label: "←", sound: "modifier" }, { code: "ArrowDown", label: "↓", sound: "modifier" }, { code: "ArrowRight", label: "→", sound: "modifier" }, ]; const ALL_DEFS: KeyDef[] = [ ...FN_ROW, ...MAIN_ROWS.flat(), ...BOTTOM_ROW, ARROW_UP_DEF, ...ARROW_ROW_DEFS, ]; const ALL_CODES = new Set(ALL_DEFS.map(d => d.code)); // Per-key backlight hue for the rgb variant — a rainbow swept left→right // across each row, drifting +12° per row for a diagonal wave. const KEY_HUE: Record = (() => { const hues: Record = {}; const assign = (row: KeyDef[], rowIdx: number, extraUnits = 0) => { const total = row.reduce((s, d) => s + (d.w ?? 1), 0) + extraUnits; let acc = 0; for (const d of row) { const center = acc + (d.w ?? 1) / 2; acc += d.w ?? 1; hues[d.code] = ((center / total) * 300 + rowIdx * 12) % 360; } return { acc, total }; }; assign(FN_ROW, 0); MAIN_ROWS.forEach((r, i) => assign(r, i + 1)); // Bottom row shares its flex track with the arrow cluster (flex 3). const { acc, total } = assign(BOTTOM_ROW, 5, 3); hues[ARROW_UP_DEF.code] = (((acc + 1.5) / total) * 300 + 5 * 12) % 360; ARROW_ROW_DEFS.forEach((d, i) => { hues[d.code] = (((acc + i + 0.5) / total) * 300 + 5 * 12) % 360; }); return hues; })(); // Theme detection for the rgb variant — bright ink means dark theme. Reads // the design-token var (CSS vars can't be used inside the per-hue oklch // palettes below) and re-reads when the theme class flips on . function useThemeIsDark(): boolean { const [dark, setDark] = useState(true); useEffect(() => { const read = () => { const raw = getComputedStyle(document.documentElement) .getPropertyValue("--ink-rgb"); const [r, g, b] = raw.split(",").map(n => parseFloat(n)); if (Number.isFinite(r) && Number.isFinite(g) && Number.isFinite(b)) { setDark((r + g + b) / 3 > 127); } }; read(); const mo = new MutationObserver(read); mo.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "data-theme"], }); return () => mo.disconnect(); }, []); return dark; } interface SingleKeyProps { def: KeyDef; active: boolean; depth: number; rgb: boolean; dark: boolean; height: number; onPress: () => void; onRelease: () => void; glowRef: (el: HTMLSpanElement | null) => void; } function SingleKey({ def, active, depth, rgb, dark, height, onPress, onRelease, glowRef, }: SingleKeyProps) { const [hovered, setHovered] = useState(false); const [mouseDown, setMouseDown] = useState(false); const pressed = active || mouseDown; const isModLike = def.sound === "modifier" || def.sound === "fn"; const hasSub = Boolean(def.sub); const isWide = (def.w ?? 1) > 1.2; const labelSize = isModLike ? "8px" : hasSub ? "10px" : "11px"; const hue = KEY_HUE[def.code] ?? 250; return (
setHovered(true)} onMouseLeave={() => { setHovered(false); setMouseDown(false); }} onMouseDown={e => { e.preventDefault(); setMouseDown(true); onPress(); }} onMouseUp={() => { setMouseDown(false); onRelease(); }} > {rgb && ( )} {hasSub && ( {def.sub} )} {def.label}
); } export interface MechanicalKeyboardProps { className?: string; enableSound?: boolean; showPreview?: boolean; variant?: "default" | "rgb"; keyDepth?: number; onKeyPress?: (code: string) => void; } const KB_H_BASE = 12 + FN_H + 5 * GAP + 5 * KEY_H + 16; // Preview text has no forced line-break — a run typed without ever hitting // Space is one unbreakable string that CSS can't wrap, so it would otherwise // overflow the board's width. Cap it well inside the 680px board (mono // glyphs at 17px run ~10.5px wide) so it always auto-clears before that. const MAX_PREVIEW_CHARS = 48; export function MechanicalKeyboard({ className, enableSound = true, showPreview = false, variant = "default", keyDepth = 3, onKeyPress, }: MechanicalKeyboardProps) { const [active, setActive] = useState>(new Set()); const [word, setWord] = useState(""); const hoveredRef = useRef(false); const audioCtxRef = useRef(null); const pendingRef = useRef(new Map()); const containerRef = useRef(null); const outerRef = useRef(null); const bodyRef = useRef(null); const isRgb = variant === "rgb"; const isDark = useThemeIsDark(); // ── RGB ripple engine ──────────────────────────────────────────── // On press, an expanding color wavefront lights each key's glow overlay // in its own hue. Driven imperatively (direct style.opacity writes) so // ~90 keys never re-render per frame. const glowEls = useRef(new Map()); const keyCenters = useRef(new Map()); const ripplesRef = useRef<{ cx: number; cy: number; t0: number }[]>([]); const rippleRaf = useRef(0); const rippleFrame = useCallback((now: number) => { const RIPPLE_MS = 650; const SPEED = 0.9; // wavefront px/ms (screen px, scales with board) const SIGMA = 34; // wavefront thickness ripplesRef.current = ripplesRef.current.filter(r => now - r.t0 < RIPPLE_MS); glowEls.current.forEach((el, code) => { const c = keyCenters.current.get(code); if (!c) return; let g = 0; for (const r of ripplesRef.current) { const t = now - r.t0; const d = Math.hypot(c.x - r.cx, c.y - r.cy); const front = t * SPEED; g += Math.exp(-((d - front) ** 2) / (2 * SIGMA * SIGMA)) * (1 - t / RIPPLE_MS); } el.style.opacity = Math.min(1, g).toFixed(3); }); rippleRaf.current = ripplesRef.current.length ? requestAnimationFrame(rippleFrame) : 0; }, []); const startRipple = useCallback( (code: string) => { if (!isRgb) return; if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return; // Re-measure at the start of a ripple burst — layout/scale may have // changed since the last one, and this forces layout only once. if (ripplesRef.current.length === 0) { keyCenters.current.clear(); glowEls.current.forEach((el, c) => { const r = el.getBoundingClientRect(); keyCenters.current.set(c, { x: r.left + r.width / 2, y: r.top + r.height / 2 }); }); } const center = keyCenters.current.get(code); if (!center) return; ripplesRef.current.push({ cx: center.x, cy: center.y, t0: performance.now() }); if (!rippleRaf.current) rippleRaf.current = requestAnimationFrame(rippleFrame); }, [isRgb, rippleFrame], ); useEffect(() => () => cancelAnimationFrame(rippleRaf.current), []); const [scale, setScale] = useState(1); const [bodyH, setBodyH] = useState(KB_H_BASE); useEffect(() => { const outer = outerRef.current; const body = bodyRef.current; if (!outer || !body) return; const ro = new ResizeObserver(() => { const availW = outer.getBoundingClientRect().width; const bH = body.offsetHeight; if (availW > 0) setScale(Math.min(1, availW / KB_W)); if (bH > 0) setBodyH(bH); }); ro.observe(outer); ro.observe(body); return () => ro.disconnect(); }, []); const getCtx = useCallback((): AudioContext | null => { if (!enableSound) return null; try { const AC = window.AudioContext || (window as unknown as { webkitAudioContext: typeof AudioContext }) .webkitAudioContext; if (!audioCtxRef.current || audioCtxRef.current.state === "closed") { audioCtxRef.current = new AC(); } return audioCtxRef.current; } catch { return null; } }, [enableSound]); const sound = useCallback( (phase: SoundPhase, type: KeySoundType = "alpha") => { const ctx = getCtx(); if (!ctx) return; const go = () => playKeySound(ctx, phase, type); ctx.state === "suspended" ? ctx.resume().then(go) : go(); }, [getCtx], ); const handlePreviewKey = useCallback( (def: KeyDef, physicalKey?: string) => { if (!showPreview) return; if (def.code === "Space") { setWord(""); return; } if (def.code === "Backspace") { setWord(w => w.slice(0, -1)); return; } if (def.sound === "modifier" || def.sound === "fn") return; if (def.code === "Enter") return; let ch: string; if (physicalKey && physicalKey.length === 1) { ch = physicalKey; } else if (def.label.length === 1) { ch = def.label.toLowerCase(); } else { return; } setWord(w => (w.length >= MAX_PREVIEW_CHARS ? ch : w + ch)); }, [showPreview], ); const pressKey = useCallback( (def: KeyDef, physicalKey?: string) => { sound("press", def.sound ?? "alpha"); pendingRef.current.set(def.code, def.sound ?? "alpha"); startRipple(def.code); handlePreviewKey(def, physicalKey); onKeyPress?.(def.code); }, [sound, startRipple, handlePreviewKey, onKeyPress], ); const releaseKey = useCallback( (def: KeyDef) => { const type = pendingRef.current.get(def.code); if (type !== undefined) { sound("release", type); pendingRef.current.delete(def.code); } }, [sound], ); useEffect(() => { const down = (e: KeyboardEvent) => { if (!hoveredRef.current || e.repeat || !ALL_CODES.has(e.code)) return; // Space/arrows/Tab scroll or shift focus by default — this keyboard // owns the keystroke while hovered, so stop the browser from also // acting on it (e.g. Space scrolling the docs page to the bottom). if (!e.metaKey && !e.ctrlKey && !e.altKey) e.preventDefault(); setActive(prev => new Set([...prev, e.code])); const def = ALL_DEFS.find(d => d.code === e.code); if (def) pressKey(def, e.key); }; const up = (e: KeyboardEvent) => { if (!ALL_CODES.has(e.code)) return; setActive(prev => { const next = new Set(prev); next.delete(e.code); return next; }); const def = ALL_DEFS.find(d => d.code === e.code); if (def) releaseKey(def); }; document.addEventListener("keydown", down); document.addEventListener("keyup", up); return () => { document.removeEventListener("keydown", down); document.removeEventListener("keyup", up); }; }, [pressKey, releaseKey]); const rowProps = (def: KeyDef) => ({ def, active: active.has(def.code), depth: keyDepth, rgb: isRgb, dark: isDark, onPress: () => pressKey(def), onRelease: () => releaseKey(def), glowRef: (el: HTMLSpanElement | null) => { if (el) glowEls.current.set(def.code, el); else glowEls.current.delete(def.code); }, }); return (
{ hoveredRef.current = true; }} onMouseLeave={() => { hoveredRef.current = false; }} >
{showPreview && (
{word || " "}
)}
{FN_ROW.map(def => ( ))}
{MAIN_ROWS.map((row, ri) => (
{row.map(def => ( ))}
))}
{BOTTOM_ROW.map(def => ( ))}
{ARROW_ROW_DEFS.map(def => ( ))}
); } export default MechanicalKeyboard; ``` ## Demo ```tsx "use client"; import React, { useState } from "react"; import { MechanicalKeyboard } from "../mellow/mechanical-keyboard"; export default function MechanicalKeyboardDemo() { const [sound, setSound] = useState(true); const [preview, setPreview] = useState(false); const [rgb, setRgb] = useState(false); return (
{/* Controls */}
{( [ { label: "Sound", active: sound, toggle: () => setSound(v => !v) }, { label: "Preview", active: preview, toggle: () => setPreview(v => !v) }, { label: "RGB", active: rgb, toggle: () => setRgb(v => !v) }, ] as const ).map(({ label, active, toggle }) => ( ))}
{/* Keyboard */}

hover keyboard · then type

); } ```