72Começar
HextaUI

Kbd

Teclas para atalhos que mostram os símbolos certos em cada plataforma, são lidas corretamente por leitores de tela e afundam com as teclas reais.

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>
  )
}

Instalação

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

Adiciona o componente, os tokens de tema do HextaUI e quaisquer componentes do HextaUI dos quais ele depende.

Uso

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

Escreva os atalhos uma vez com keys e eles aparecem como ⌘K no Mac e Ctrl K no Windows e no Linux. Ou passe qualquer conteúdo como children para ter controle total.

Composição

Kbd

KbdGroup
└── Kbd

Exemplos

Variantes

keycap tem uma borda fina e um relevo de 1px para parecer uma tecla física. flat é um preenchimento discreto para lugares densos como 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>
  )
}

Tamanhos

sm fica em texto pequeno, default ao lado do texto do corpo e lg em títulos ou sozinho.

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>
  )
}

Atalhos

<KbdGroup /> divide uma combinação em uma tecla para cada tecla. Um espaço inicia uma sequência, unida por separator. <Kbd /> com keys mantém a combinação inteira em uma só tecla.

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>
  )
}

Teclas ao vivo

Com listen, uma tecla é pressionada enquanto a tecla real está segurada. Ela apenas observa, então nunca bloqueia, atrasa nem altera o que você digita. As letras correspondem pela tecla física, então Option e Shift não as confundem.

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>
  )
}

Em um botão

Dentro de um botão, a tecla toma as cores do texto do botão, então combina com todas as 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>
  )
}

Ícones e ações

Coloque ícones em uma tecla para ações sem nome de tecla e dê a eles um rótulo visualmente oculto.

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>
  )
}

Da direita para a esquerda

Os atalhos permanecem na ordem da esquerda para a direita dentro de textos da direita para a esquerda, como impressos no teclado.

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>
  )
}

Acessibilidade

  • Símbolos como ⌘ e ⇧ ficam ocultos dos leitores de tela e são substituídos pelos seus nomes, então keys="mod+shift+p" é lido como "Command Shift P".
  • As teclas são renderizadas como <kbd>, e um grupo as aninha em outro <kbd>, que é como o HTML marca uma combinação de teclas.
  • Exibir um atalho não o registra. Registre você mesmo o handler da tecla.
  • O efeito de pressionar é decorativo, com uma mudança de cor no lugar do movimento quando o movimento reduzido está ativado. Antes da hidratação, toda plataforma vê os símbolos da Apple.

Referência da API

Ambas as partes renderizam um <kbd> e aceitam render e seus atributos.

Kbd

PropTipoPadrão
keysTeclas unidas por +, como "mod+shift+p". mod é ⌘ em dispositivos Apple e Ctrl nos demais. Nomes como alt, enter, escape, up e space viram símbolos ou palavras curtas, e recebem um nome falado para leitores de tela.
string–
variantHerdado do KbdGroup quando não definido.
"keycap" | "flat""keycap"
sizeHerdado do KbdGroup quando não definido.
"sm" | "default" | "lg""default"
listenPressiona a tecla enquanto a tecla real está pressionada. Funciona com keys ou com o nome simples de uma tecla como children.
booleanfalse
render
ReactElement | (props, state) => ReactElement<kbd>
AtributoDescrição
data-slot="kbd"Seleciona as teclas no CSS.
data-variantA variante atual.
data-sizeO tamanho atual.
data-pressedPresente enquanto a tecla real está pressionada.

KbdGroup

PropTipoPadrão
keysTeclas unidas por +, como "mod+shift+p". mod é ⌘ em dispositivos Apple e Ctrl nos demais. Nomes como alt, enter, escape, up e space viram símbolos ou palavras curtas, e recebem um nome falado para leitores de tela. Espaços separam as etapas de uma sequência.
string–
separatorExibido entre as etapas de uma sequência.
ReactNode"then"
variantRepassado a todas as teclas dentro do grupo.
"keycap" | "flat"–
sizeRepassado a todas as teclas dentro do grupo.
"sm" | "default" | "lg"–
listenRepassado a todas as teclas dentro do grupo.
boolean–
render
ReactElement | (props, state) => ReactElement<kbd>
AtributoDescrição
data-slot="kbd-group"Selecione grupos no CSS.
data-slot="kbd-separator"O texto entre as etapas da sequência.

Relacionados

Usado em blocos

Blocos que se baseiam em Kbd.