A compact accessible keycap sequence paired with the action it performs.
import { ShortcutHint } from "@/components/ballmac/shortcut-hint"
export default function ShortcutHintDemo() {
return (
<div className="bg-card flex w-full max-w-xs flex-col gap-1 rounded-xl border border-border p-2 shadow-sm">
<div className="hover:bg-accent rounded-md px-3 py-2">
<ShortcutHint
className="w-full justify-between"
label="Search anything"
keys={["⌘", "K"]}
/>
</div>
<div className="hover:bg-accent rounded-md px-3 py-2">
<ShortcutHint
className="w-full justify-between"
label="Create project"
keys={["⌘", "N"]}
/>
</div>
</div>
)
}Installation
$ pnpm dlx shadcn@latest add @ballmac/shortcut-hintAdd the Ballmac items it builds on.
$ pnpm dlx shadcn@latest add @ballmac/i18nCopy the source into your project.
components/ballmac/shortcut-hint.tsx// Ballmac UI: Shortcut Hint. https://ui.ballmac.com/components/shortcut-hint "use client" import * as React from "react" import { cn } from "@/lib/utils" import { useMessages } from "@/lib/ballmac/i18n" type ShortcutHintProps = React.ComponentProps<"span"> & { /** Keys in order, such as ["⌘", "K"]. */ keys: string[] /** Action explained by the shortcut. */ label: string /** Render compact keycaps for dense menus. */ compact?: boolean } function ShortcutHint({ className, keys, label, compact = false, ...props }: ShortcutHintProps) { const msg = useMessages() return ( <span data-slot="shortcut-hint" role="note" aria-label={msg("shortcut-hint.label", "{label}: {keys}", { label, keys: keys.join(msg("shortcut-hint.plus", " plus ")) })} className={cn( "inline-flex min-w-0 items-center gap-1 text-sm", className, )} {...props} > <span aria-hidden="true" className="text-muted-foreground me-1 truncate"> {label} </span> <span aria-hidden="true" className="inline-flex shrink-0 items-center gap-0.5" > {keys.map((key, index) => ( <kbd key={`${key}-${index}`} data-slot="shortcut-hint-key" className={cn( "bg-muted text-muted-foreground inline-flex items-center justify-center rounded border border-border font-mono shadow-sm", compact ? "min-w-5 px-1 py-0.5 text-[10px]" : "min-w-6 px-1.5 py-0.5 text-xs", )} > {key} </kbd> ))} </span> </span> ) } export { ShortcutHint, type ShortcutHintProps }Update the import paths to match your project setup.
Usage
import { ShortcutHint } from "@/components/ballmac/shortcut-hint"The full example is in the Code tab above.
Examples
States and variants
import { ShortcutHint } from "@/components/ballmac/shortcut-hint"
export default function ShortcutHintStates() {
return (
<div className="flex w-full max-w-xs flex-col items-start gap-3">
<ShortcutHint compact label="Save" keys={["Ctrl", "S"]} />
<ShortcutHint label="Open command menu" keys={["⇧", "⌘", "P"]} />
</div>
)
}API reference
| Prop | Type | Default |
|---|---|---|
keys*Keys in order, such as ["⌘", "K"]. | string[] | — |
label*Action explained by the shortcut. | string | — |
compactRender compact keycaps for dense menus. | boolean | false |
Also accepts the standard attributes of its root element.
Accessibility
| Key | Action |
|---|---|
| None | Full shortcut meaning is in the accessible name |
Quality scorecard
Every applicable check passes
Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.0.0, across 2 examples.
Passed: Accessibility scan
No serious or critical issues in light and dark, on a phone and a desktop (axe-core 4.13.0, WCAG 2.1 AA and best-practice rules).
Passed: Small screens
No sideways scrolling at 360, 390 or 1280 px wide.
Passed: Reduced motion
No endless animation to begin with.
Passed: Right to left
Mirrors correctly in Arabic, Hebrew, Persian and Urdu layouts (0% of elements off the mirror, limit 15%).
Passed: Clean console
No console errors or React hydration errors while loading.
Not applicable: Keyboard
Static content: nothing to focus.
Not applicable: Loading, empty and error
Does not show data or take submissions.
For information: Automated tests
No test file of its own yet.
For information: Footprint
0.8 KB of source (gzip) in 1 file. No extra npm packages.
Automated checks find a subset of problems and do not replace testing with a screen reader and a keyboard in your own app. What they miss.
Use with AI
A compact accessible keycap sequence paired with the action it performs. With the shadcn MCP server set up (guide), ask your agent:
Add the Ballmac UI Shortcut Hint (@ballmac/shortcut-hint) to this project with the shadcn MCP, then use it where it fits.
Use it for
- Label a command in a menu
- Teach an optional keyboard shortcut
Not for
- Use kbd for an isolated key
Registry JSON: https://ui.ballmac.com/r/shortcut-hint.json
Credits
Free to use in personal and commercial projects.
- npm
- None
- Registry
- @ballmac/i18nshadcn/utils
Pairs well with
Kbd
Keyboard key and shortcut display built on the semantic <kbd> element, in three sizes, with KbdGroup for combinations like ⌘ ⇧ K. Adapts inside tooltips.
Spotlight Search
A macOS Spotlight-style command palette on cmdk: a large translucent search field, grouped results with app-icon tiles, fuzzy filtering and arrow-key navigation, inline or as a ⌘K dialog.
Alert Dialog
Focus-managed confirmation for consequential actions, with a clear cancel path, optional media, and a token-based destructive action.
Alert
A semantic callout with five theme-aware tones, clear icon placement, an action row, and opt-in urgent announcements.
Ballmac UI Pro
Need the whole screen, not one piece?
311 premium blocks (dashboards, settings, calendars, mail, shops, onboarding), a private shadcn registry and Figma tokens. Blocks that show data come with loading, empty and error states built in.
Not ready? Try three Pro blocks free
Leave your email and the blocks appear right here, ready to copy. Yours to use in any project.