Combo kbd
Five ways to render a multi-key shortcut: plain caps, a joined chain, a plus connector, a then sequence and a bordered group. Each renders real kbd elements and carries a visually hidden label so a screen reader reads the full combination, such as Control plus K.
Installation
The styled layer is free and installs like any other ai2 component.
Run the following command
npx shadcn@latest add @ai2/kbd-comboDependencies, the @ai2/tokens theme and the component file are installed together.
Copy the source
components/ui/kbd-combo.tsx"use client"
import * as React from "react"
import { cn } from "@/lib/utils"
/* Combo kbd family: multi-key combinations. Every variant carries real <kbd> caps inside a root <kbd>; for accessibility the root holds the sr-only full text ("Ctrl plus K") and the visual cap stack is aria-hidden, so a screen reader hears one readable name. Colour comes ONLY from tokens. Static - no motion. */
export type StyledSize = "sm" | "md" | "lg" | "xl"
const box: Record<StyledSize, string> = {
sm: "h-5 px-1.5 text-xs",
md: "h-6 px-2 text-xs",
lg: "h-7 px-2.5 text-sm",
xl: "h-8 px-3 text-sm",
}
const gap: Record<StyledSize, string> = {
sm: "gap-1",
md: "gap-1",
lg: "gap-1.5",
xl: "gap-1.5",
}
const conn: Record<StyledSize, string> = {
sm: "text-[10px]",
md: "text-xs",
lg: "text-xs",
xl: "text-sm",
}
const rootBase =
"inline-flex w-fit shrink-0 select-none items-center whitespace-nowrap font-mono font-medium leading-none text-foreground"
const capBase =
"inline-flex shrink-0 select-none items-center justify-center gap-1 whitespace-nowrap rounded-md border border-border bg-surface-2 font-mono font-medium leading-none text-foreground [&_svg]:size-3 [&_svg]:shrink-0 [&_i]:text-xs [&_i]:leading-none"
type Props = React.ComponentProps<"kbd"> & {
size?: StyledSize
/** Cap texts; the variant default is used when none are given. */
keys?: string[]
}
/* Tek kapak. */
function Cap({ size, children }: { size: StyledSize; children: React.ReactNode }) {
return <kbd className={cn(capBase, box[size])}>{children}</kbd>
}
/* The full combination text for screen readers ("Ctrl plus K" / "G then P"). */
function label(keys: string[], word: string) {
return keys.join(` ${word} `)
}
/* Combo: sade yan yana kapaklar, baglayici yok. */
export function ComboKbd({ className, size = "md", keys, children, ...props }: Props) {
const list = keys ?? ["Ctrl", "K"]
return (
<kbd data-slot="styled-kbd" className={cn(rootBase, gap[size], className)} {...props}>
{children ?? (
<>
<span className="sr-only">{label(list, "plus")}</span>
<span aria-hidden="true" className={cn("inline-flex items-center", gap[size])}>
{list.map((k, i) => (
<Cap key={`${k}-${i}`} size={size}>
{k}
</Cap>
))}
</span>
</>
)}
</kbd>
)
}
/* Chain: segments joined inside a single shell, divided by separator lines. */
export function ChainKbd({ className, size = "md", keys, children, ...props }: Props) {
const list = keys ?? ["Ctrl", "Shift", "P"]
return (
<kbd
data-slot="styled-kbd"
className={cn(
rootBase,
"overflow-hidden rounded-md border border-border bg-surface-2",
className
)}
{...props}
>
{children ?? (
<>
<span className="sr-only">{label(list, "plus")}</span>
<span aria-hidden="true" className="inline-flex items-center divide-x divide-border">
{list.map((k, i) => (
<kbd
key={`${k}-${i}`}
className={cn(
"inline-flex shrink-0 items-center justify-center whitespace-nowrap font-mono font-medium leading-none [&_svg]:size-3 [&_svg]:shrink-0 [&_i]:text-xs [&_i]:leading-none",
box[size]
)}
>
{k}
</kbd>
))}
</span>
</>
)}
</kbd>
)
}
/* Plus: kapaklar arasinda gorunur bir "+" baglayici. */
export function PlusKbd({ className, size = "md", keys, children, ...props }: Props) {
const list = keys ?? ["Cmd", "S"]
return (
<kbd data-slot="styled-kbd" className={cn(rootBase, gap[size], className)} {...props}>
{children ?? (
<>
<span className="sr-only">{label(list, "plus")}</span>
<span aria-hidden="true" className={cn("inline-flex items-center", gap[size])}>
{list.map((k, i) => (
<React.Fragment key={`${k}-${i}`}>
{i > 0 ? (
<span className={cn("text-muted-foreground", conn[size])}>+</span>
) : null}
<Cap size={size}>{k}</Cap>
</React.Fragment>
))}
</span>
</>
)}
</kbd>
)
}
/* Sequence: once X sonra Y - kapaklar arasinda "then" baglayicisi. */
export function SequenceKbd({ className, size = "md", keys, children, ...props }: Props) {
const list = keys ?? ["G", "P"]
return (
<kbd data-slot="styled-kbd" className={cn(rootBase, gap[size], className)} {...props}>
{children ?? (
<>
<span className="sr-only">{label(list, "then")}</span>
<span aria-hidden="true" className={cn("inline-flex items-center", gap[size])}>
{list.map((k, i) => (
<React.Fragment key={`${k}-${i}`}>
{i > 0 ? (
<span className={cn("font-sans lowercase text-muted-foreground", conn[size])}>
then
</span>
) : null}
<Cap size={size}>{k}</Cap>
</React.Fragment>
))}
</span>
</>
)}
</kbd>
)
}
/* Group: kapaklar tek bir cerceveli kap icinde toplanir. */
export function GroupKbd({ className, size = "md", keys, children, ...props }: Props) {
const list = keys ?? ["Alt", "Enter"]
return (
<kbd
data-slot="styled-kbd"
className={cn(
rootBase,
"rounded-lg border border-border bg-[color-mix(in_oklab,var(--color-foreground)_4%,transparent)] p-1",
gap[size],
className
)}
{...props}
>
{children ?? (
<>
<span className="sr-only">{label(list, "plus")}</span>
<span aria-hidden="true" className={cn("inline-flex items-center", gap[size])}>
{list.map((k, i) => (
<Cap key={`${k}-${i}`} size={size}>
{k}
</Cap>
))}
</span>
</>
)}
</kbd>
)
}Manual installs skip the @ai2/tokens theme, so add the token CSS from the theming guide or the tone colors will be missing.
Variations
5 takes on the same idea. Each is its own export, and every one accepts a size prop (sm, md, lg, xl) aligned to the base Button scale.
Combo
Plain side-by-side keycaps with no connector.
import { ComboKbd } from "@/components/ui/kbd-combo"
<ComboKbd />Chain
Segments joined into one shell with divider rules.
import { ChainKbd } from "@/components/ui/kbd-combo"
<ChainKbd />Plus
Keycaps separated by a visible plus connector.
import { PlusKbd } from "@/components/ui/kbd-combo"
<PlusKbd />Sequence
Press one key then the next, joined by a then connector.
import { SequenceKbd } from "@/components/ui/kbd-combo"
<SequenceKbd />Group
Keycaps collected inside a single bordered container.
import { GroupKbd } from "@/components/ui/kbd-combo"
<GroupKbd />ai2 Combo kbd: 5 styled variations on the token system
The ai2 Combo kbd are a set of 5 decorative button variations from the styled layer of the @ai2 design system, built around multi-key keyboard shortcut combinations. They are free and MIT licensed, and every color comes from a semantic token, so they theme with the rest of ai2 in light and dark.
Motion runs on framer-motion: these are static, so no motion library work is required. The styled layer is opt-in, so the dependency only lands if you use it; the base components stay lean. Under reduced motion, there is no continuous motion to reduce.
What is in the ai2 Combo kbd?
5 exports in one file: Combo, Chain, Plus, Sequence and Group. Each renders a native button and takes a size prop (sm, md, lg, xl) aligned to the base Button. They are separate from the base Button on purpose: the base keeps its clean variant, tone and size axes, while the styled layer carries the effects.
You own the file. Copy the one category file and you have all 5 variations, with no runtime dependency on ai2 itself.
Why use it
- On-system by construction: Every color resolves to an ai2 semantic token, so the buttons follow your theme in light and dark with no extra work.
- Effect without the sprawl: The decorations live in a dedicated styled file, so the base Button keeps its clean, predictable API.
- Accessible and honest: Each renders a real button element, keeps a visible focus ring, and respects prefers-reduced-motion.
Features
- Token-driven color: No hardcoded hex or oklch; the look recolors with your theme tokens.
- framer-motion: these are static, so no motion library work is required.
- Reduced-motion aware: Under prefers-reduced-motion, there is no continuous motion to reduce.
- Size aligned to the base: Every variation takes sm, md, lg and xl matching the base Button height scale, so styled and base buttons line up in a row.
Production tips
- Use it for emphasis, not everywhere: Styled buttons draw the eye. Reserve them for the one action you want people to take on a screen, and use the base Button for the rest.
- Keep labels as verbs: The decoration adds weight, so a clear action label keeps the button scannable.
- Pick one variation per surface: The variations share a family; using two different ones in the same view competes for attention.
Works with the rest of ai2
The Combo kbd sit alongside the base Button and the rest of the @ai2 registry. They share the same token file, so a styled action next to a base button or a badge stays visually consistent in both modes.