72Commencer
HextaUI

Kbd

Des keycaps pour les raccourcis qui affichent les bons symboles sur chaque plateforme, se lisent correctement à voix haute et s’enfoncent comme de vraies touches.

ShiftCommandP

Press Command K to search, or hold Shift and watch the keys.

import { Kbd, KbdGroup } from "@/components/ui/kbd"

export function KbdDemo() {
  return (
    <div className="flex flex-col items-center gap-6 text-sm text-muted-foreground">
      <KbdGroup keys="mod+shift+p" size="lg" listen />
      <p>
        Press <Kbd keys="mod+k" listen /> to search, or hold{" "}
        <Kbd keys="shift" listen /> and watch the keys.
      </p>
    </div>
  )
}

Installation

pnpm dlx shadcn@latest add https://hextaui.com/r/kbd.json

Ajoute le composant, les tokens de thème HextaUI et les composants HextaUI dont il dépend.

Utilisation

import { Kbd, KbdGroup } from "@/components/ui/kbd"
<KbdGroup keys="mod+k" />
<Kbd keys="escape" />
<Kbd>K</Kbd>

Écrivez les raccourcis une fois avec keys : ils s'affichent ⌘K sur Mac et Ctrl K sous Windows et Linux. Ou passez n'importe quel contenu en enfants pour un contrôle total.

Composition

Kbd

KbdGroup
└── Kbd

Exemples

Variantes

keycap a un bord fin et un rebord de 1px pour ressembler à une vraie touche. flat est un fond discret pour les endroits denses comme les menus.

import { KbdGroup } from "@/components/ui/kbd"

export function KbdVariants() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-6">
      <KbdGroup keys="mod+c" />
      <KbdGroup keys="mod+c" variant="flat" />
    </div>
  )
}

Tailles

sm s'insère dans un petit texte, default à côté du texte courant et lg dans les titres ou seul.

import { KbdGroup } from "@/components/ui/kbd"

const sizes = ["sm", "default", "lg"] as const

export function KbdSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-6">
      {sizes.map((size) => (
        <KbdGroup key={size} keys="mod+shift+z" size={size} />
      ))}
    </div>
  )
}

Raccourcis

<KbdGroup /> découpe une combinaison en une touche par capuchon. Un espace démarre une séquence, jointe par separator. <Kbd /> avec keys garde toute la combinaison dans un seul capuchon.

import { Kbd, KbdGroup } from "@/components/ui/kbd"

const shortcuts = [
  { label: "Command palette", keys: "mod+k" },
  { label: "Move line up", keys: "alt+up" },
  { label: "Close", keys: "escape" },
  { label: "Go to dashboard", keys: "g d" },
]

export function KbdShortcuts() {
  return (
    <dl className="grid w-full max-w-xs grid-cols-[1fr_auto] items-center gap-x-6 gap-y-3 text-sm">
      {shortcuts.map((shortcut) => (
        <div key={shortcut.keys} className="contents">
          <dt className="text-muted-foreground">{shortcut.label}</dt>
          <dd>
            <KbdGroup keys={shortcut.keys} />
          </dd>
        </div>
      ))}
      <dt className="text-muted-foreground">Save, as one cap</dt>
      <dd>
        <Kbd keys="mod+s" />
      </dd>
    </dl>
  )
}

Touches en direct

Avec listen, un capuchon s'enfonce tant que sa vraie touche est maintenue. Il ne fait qu'observer : il ne bloque, ne retarde ni ne modifie jamais ce que vous saisissez. Les lettres correspondent à la touche physique, donc Option et Maj ne les perturbent pas.

import { Kbd, KbdGroup } from "@/components/ui/kbd"

const rows = ["qwertyuiop", "asdfghjkl", "zxcvbnm"]

export function KbdListen() {
  return (
    <KbdGroup listen size="lg" className="flex-col">
      {rows.map((row) => (
        <span key={row} className="flex gap-1">
          {row.split("").map((key) => (
            <Kbd key={key}>{key.toUpperCase()}</Kbd>
          ))}
        </span>
      ))}
      <span className="flex gap-1">
        <Kbd keys="shift" />
        <Kbd keys="space" className="min-w-40" />
        <Kbd keys="enter" />
      </span>
    </KbdGroup>
  )
}

Dans un bouton

Dans un bouton, le capuchon reprend les couleurs du texte du bouton et convient donc à toutes les variantes.

import { IconSearch } from "@tabler/icons-react"

import { Button } from "@/components/ui/button"
import { Kbd } from "@/components/ui/kbd"

export function KbdButton() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      <Button variant="outline">
        <IconSearch data-icon="inline-start" />
        Search
        <Kbd keys="mod+k" />
      </Button>
      <Button>
        Save
        <Kbd keys="mod+s" />
      </Button>
      <Button variant="ghost">
        Undo
        <Kbd keys="mod+z" variant="flat" />
      </Button>
    </div>
  )
}

Icônes et actions

Placez des icônes dans un capuchon pour les actions sans nom de touche, et donnez-leur un label visuellement masqué.

import { IconArrowBackUp, IconClick } from "@tabler/icons-react"

import { Kbd, KbdGroup } from "@/components/ui/kbd"

export function KbdComposed() {
  return (
    <div className="flex flex-col items-center gap-3 text-sm text-muted-foreground">
      <p className="flex items-center gap-2">
        <KbdGroup>
          <Kbd keys="shift" />
          <Kbd>
            <IconClick aria-hidden="true" />
            <span className="sr-only">Click</span>
          </Kbd>
        </KbdGroup>
        to select a range
      </p>
      <p className="flex items-center gap-2">
        <Kbd>
          <IconArrowBackUp aria-hidden="true" />
          <span className="sr-only">Backspace</span>
        </Kbd>
        to go back
      </p>
    </div>
  )
}

De droite à gauche

Les raccourcis restent dans l'ordre de gauche à droite au sein d'un texte de droite à gauche, comme ils sont imprimés sur le clavier.

import { Kbd, KbdGroup } from "@/components/ui/kbd"

export function KbdRtl() {
  return (
    <p
      dir="rtl"
      className="flex items-center gap-2 text-sm text-muted-foreground"
    >
      اضغط
      <KbdGroup keys="mod+shift+p" />
      لفتح لوحة الأوامر، أو <Kbd keys="escape" /> للإغلاق
    </p>
  )
}

Accessibilité

  • Les symboles comme ⌘ et ⇧ sont masqués aux lecteurs d'écran et remplacés par leur nom, si bien que keys="mod+shift+p" est lu « Command Shift P ».
  • Les capuchons sont rendus en <kbd>, et un groupe les imbrique dans un autre <kbd>, ce qui est la façon dont HTML représente une combinaison de touches.
  • Afficher un raccourci ne le lie à aucune action. Enregistrez vous-même le gestionnaire de touche.
  • L'effet d'appui est décoratif, avec un changement de couleur à la place du mouvement quand la réduction des animations est activée. Avant l'hydratation, toutes les plateformes voient les symboles Apple.

Référence de l’API

Les deux parties rendent un <kbd> et acceptent render et ses attributs.

Kbd

PropTypePar défaut
keysTouches jointes par +, comme "mod+shift+p". mod est ⌘ sur les appareils Apple et Ctrl ailleurs. Des noms comme alt, enter, escape, up et space deviennent des symboles ou des mots courts, et reçoivent un nom parlé pour les lecteurs d'écran.
string–
variantHérité de KbdGroup si non défini.
"keycap" | "flat""keycap"
sizeHérité de KbdGroup si non défini.
"sm" | "default" | "lg""default"
listenEnfonce le capuchon tant que sa vraie touche est maintenue. Fonctionne avec keys ou un simple nom de touche en enfant.
booleanfalse
render
ReactElement | (props, state) => ReactElement<kbd>
AttributDescription
data-slot="kbd"Cible les capuchons en CSS.
data-variantLa variante actuelle.
data-sizeLa taille actuelle.
data-pressedPrésent tant que la vraie touche est maintenue.

KbdGroup

PropTypePar défaut
keysTouches jointes par +, comme "mod+shift+p". mod est ⌘ sur les appareils Apple et Ctrl ailleurs. Des noms comme alt, enter, escape, up et space deviennent des symboles ou des mots courts, et reçoivent un nom parlé pour les lecteurs d'écran. Les espaces séparent les étapes d'une séquence.
string–
separatorAffiché entre les étapes d'une séquence.
ReactNode"then"
variantTransmis à chaque capuchon à l'intérieur.
"keycap" | "flat"–
sizeTransmis à chaque capuchon à l'intérieur.
"sm" | "default" | "lg"–
listenTransmis à chaque capuchon à l'intérieur.
boolean–
render
ReactElement | (props, state) => ReactElement<kbd>
AttributDescription
data-slot="kbd-group"Ciblez les groupes en CSS.
data-slot="kbd-separator"Le texte entre les étapes d'une séquence.

Voir aussi

Utilisé dans les blocks

Des blocks qui s’appuient sur Kbd.