Keycap button
Buttons that feel like physical keys, in three materials behind one API: raised keycaps on a darker base edge that sink when pressed, soft keys lifted out of the surface by a light and a dark shadow that turn inward on press, and inset keys carved into the panel that press deeper. Primary, neutral and destructive tones mix their shadows from theme tokens, so dark mode works. Keys can print a tiny corner legend such as a shortcut letter, and a latched mode turns any key into a toggle that rests half-pressed while on. Space and Enter show the same press as the pointer, icon keys warn in the console when they lack a label, and the sink movement is dropped under reduced motion.
Source
"use client";
import { useEffect, useState, type ButtonHTMLAttributes, type KeyboardEvent, type MouseEvent, type ReactNode } from "react";
import { cn } from "@/lib/utils";
type Variant = "raised" | "soft" | "inset";
type Tone = "primary" | "neutral" | "destructive";
type Size = "sm" | "md" | "lg" | "icon";
export type KeycapButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
variant?: Variant;
tone?: Tone;
size?: Size;
/** A tiny secondary glyph printed in the top-right corner, like a shortcut letter. */
legend?: ReactNode;
/** Turns the key into a toggle that stays half-pressed while on. */
latched?: boolean;
pressed?: boolean;
defaultPressed?: boolean;
onPressedChange?: (pressed: boolean) => void;
children?: ReactNode;
};
/* Every colour is mixed from theme tokens, so the keys follow the buyer's theme into dark mode.
--kc the key's tone colour --kc-fg text on a raised key
--kc-s the surface the key sits on --kc-edge the darker base edge */
const CSS = `.chm-key{--kc:var(--primary);--kc-fg:var(--primary-foreground);--kc-ink:var(--primary);--kc-s:var(--card);--kc-edge-w:4px;
--kc-edge:color-mix(in oklab,var(--kc) 62%,#000);--kc-hi:color-mix(in oklab,var(--kc-s) 55%,#fff);--kc-lo:color-mix(in oklab,var(--kc-s) 78%,#000);
position:relative;border:0;cursor:pointer;-webkit-tap-highlight-color:transparent;transition:box-shadow .12s ease,background-color .12s ease}
.chm-key[data-tone=neutral]{--kc:var(--secondary);--kc-fg:var(--secondary-foreground);--kc-ink:var(--foreground);--kc-edge:color-mix(in oklab,var(--secondary) 72%,var(--foreground))}
.chm-key[data-tone=destructive]{--kc:var(--destructive);--kc-fg:#fff;--kc-ink:var(--destructive)}
.dark .chm-key{--kc-hi:color-mix(in oklab,var(--kc-s) 88%,#fff);--kc-lo:color-mix(in oklab,var(--kc-s) 45%,#000)}
.chm-key[data-variant=raised]{background:var(--kc);color:var(--kc-fg);
box-shadow:inset 0 1px 0 color-mix(in oklab,#fff 28%,transparent),0 var(--kc-edge-w) 0 var(--kc-edge),0 calc(var(--kc-edge-w) + 3px) 8px -2px rgb(0 0 0/.28)}
.chm-key[data-variant=raised][data-latched=on]{--kc-edge-w:2px;transform:translateY(2px);background:color-mix(in oklab,var(--kc) 80%,var(--kc-edge))}
.chm-key[data-variant=raised]:is(:active,[data-pressing]):not(:disabled){--kc-edge-w:1px;transform:translateY(3px)}
.chm-key[data-variant=soft]{background:var(--kc-s);color:var(--kc-ink);
box-shadow:-4px -4px 9px var(--kc-hi),4px 4px 10px var(--kc-lo)}
.chm-key[data-variant=soft][data-latched=on]{box-shadow:inset 2px 2px 4px var(--kc-lo),inset -2px -2px 4px var(--kc-hi)}
.chm-key[data-variant=soft]:is(:active,[data-pressing]):not(:disabled){box-shadow:inset 4px 4px 8px var(--kc-lo),inset -4px -4px 8px var(--kc-hi)}
.chm-key[data-variant=inset]{background:color-mix(in oklab,var(--kc) 12%,var(--kc-s));color:var(--kc-ink);
box-shadow:inset 0 2px 3px rgb(0 0 0/.16),inset 0 0 0 1px color-mix(in oklab,var(--kc) 22%,var(--border)),0 1px 0 var(--kc-hi)}
.chm-key[data-variant=inset][data-latched=on]{background:color-mix(in oklab,var(--kc) 22%,var(--kc-s));box-shadow:inset 0 3px 5px rgb(0 0 0/.24),inset 0 0 0 1px color-mix(in oklab,var(--kc) 35%,var(--border)),0 1px 0 var(--kc-hi)}
.chm-key[data-variant=inset]:is(:active,[data-pressing]):not(:disabled){box-shadow:inset 0 4px 8px rgb(0 0 0/.32),inset 0 0 0 1px color-mix(in oklab,var(--kc) 30%,var(--border)),0 1px 0 var(--kc-hi)}
.chm-key:disabled{cursor:not-allowed;opacity:.5}
@media (prefers-reduced-motion:no-preference){.chm-key{transition:box-shadow .12s ease,background-color .12s ease,transform .09s ease-out}}`;
const SIZES: Record<Size, string> = {
sm: "h-8 min-w-8 rounded-md px-3 text-xs",
md: "h-10 min-w-10 rounded-lg px-4 text-sm",
lg: "h-12 min-w-12 rounded-xl px-6 text-base",
icon: "size-10 rounded-lg [&_svg]:size-4",
};
export function KeycapButton({
variant = "raised", tone = "primary", size = "md", legend, latched = false,
pressed: pressedProp, defaultPressed = false, onPressedChange,
className, children, onClick, onKeyDown, onKeyUp, onBlur, type = "button", ...props
}: KeycapButtonProps) {
const [inner, setInner] = useState(defaultPressed);
const [pressing, setPressing] = useState(false);
const on = latched && (pressedProp ?? inner);
const missingName = size === "icon" && !props["aria-label"] && !props["aria-labelledby"];
useEffect(() => {
if (missingName) console.warn("KeycapButton: size=\"icon\" needs an aria-label so screen readers can name it.");
}, [missingName]);
function handleClick(event: MouseEvent<HTMLButtonElement>) {
onClick?.(event);
if (event.defaultPrevented || !latched) return;
const next = !on;
if (pressedProp === undefined) setInner(next);
onPressedChange?.(next);
}
// :active does not fire for the keyboard in every browser, so Space and Enter set the press state themselves.
function handleKeyDown(event: KeyboardEvent<HTMLButtonElement>) {
onKeyDown?.(event);
if (event.key === " " || event.key === "Enter") setPressing(true);
}
function handleKeyUp(event: KeyboardEvent<HTMLButtonElement>) {
onKeyUp?.(event);
if (event.key === " " || event.key === "Enter") setPressing(false);
}
return (
<button
type={type}
{...props}
data-variant={variant}
data-tone={tone}
data-latched={latched ? (on ? "on" : "off") : undefined}
data-pressing={pressing ? "" : undefined}
aria-pressed={latched ? on : undefined}
onClick={handleClick}
onKeyDown={handleKeyDown}
onKeyUp={handleKeyUp}
onBlur={(event) => { setPressing(false); onBlur?.(event); }}
className={cn(
"chm-key inline-flex shrink-0 select-none items-center justify-center gap-2 font-semibold",
"outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
SIZES[size],
className,
)}
>
<style href="chm-keycap-button" precedence="default">{CSS}</style>
{children}
{legend != null && (
<span aria-hidden="true" className="pointer-events-none absolute right-1.5 top-1 font-mono text-[9px] font-medium leading-none opacity-60">
{legend}
</span>
)}
</button>
);
}
