Kbd

Stabilny

Wyświetla klawisz lub skrót klawiszowy — w tekście, w menu albo w podpowiedziach.

examples/kbd/demo.tsx

⌘K

Klawisz / otwiera wyszukiwanie, a Esc zamyka.

Instalacja

$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/kbd.json

Użycie

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

<KbdGroup>
  <Kbd>⌘</Kbd>
  <Kbd>K</Kbd>
</KbdGroup>

Przykłady

Lista skrótów

KbdGroup ustawia obok siebie klawisze jednej kombinacji. Każdy fizyczny klawisz umieść w osobnym Kbd, w kolejności, w jakiej się je naciska.

examples/kbd/group.tsx

Paleta poleceń: ⌘K
Pokaż lub ukryj pasek boczny: ⌘B
Znajdź w projekcie: ⌘⇧F
Przejdź do wiersza: CtrlG
Usuń wiersz: ⌘⌫

Ucz skrótów tam, gdzie ludzie już patrzą: w podpowiedzi przycisku, który ma swój skrót. W podpowiedzi klawisze przechodzą w półprzezroczysty styl, czytelny na odwróconej powierzchni. Zadeklaruj też skrót na samej kontrolce przez aria-keyshortcuts.

examples/kbd/in-tooltip.tsx

W menu

W menu skróty trafiają do DropdownMenuShortcut, wyrównanego do końca każdej pozycji.

examples/kbd/in-menu.tsx

Zależnie od platformy

Pokazuj modyfikator, który ktoś naprawdę ma na klawiaturze: ⌘ na macOS i iOS, Ctrl wszędzie indziej. Wykrywaj platformę po stronie klienta, a na serwerze renderuj neutralną wartość domyślną, żeby uniknąć niezgodności podczas hydratacji.

examples/kbd/platform.tsx

Szukaj skrótem CtrlK

Pokazujemy skróty dla Windows i Linux — dopasowane do tego urządzenia.

function useIsApple() {
  return React.useSyncExternalStore(
    () => () => {},
    () => /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent),
    () => false
  )
}

W tekście

Klawisze stoją na linii bazowej tekstu ciągłego, więc instrukcje mogą je wymieniać w miejscu, w którym o nich mowa.

examples/kbd/in-text.tsx

Zaznacz wiersz i naciśnij Enter — otworzy się. Klawisze Shift↑ i Shift↓ rozszerzają zaznaczenie, a Esc je czyści.

Wytyczne

Kiedy używać

Do pokazania skrótu klawiszowego obok akcji, którą wywołuje.
Do wskazania klawisza w instrukcji: Naciśnij Esc, aby zamknąć.

Kiedy nie używać

Do kodu i poleceń — użyj formatowania code w tekście.
Do przycisków, które trzeba kliknąć — Kbd wygląda, jakby dało się go wcisnąć, ale to tylko pozór.

Symbole i nazwy

Używaj symboli nadrukowanych na klawiszach tam, gdzie są jednoznaczne, a słów tam, gdzie nie są.

Klawisz	Zapis
Command, Option, Shift, Control (macOS)	⌘ ⌥ ⇧ ⌃
Control, Alt (Windows, Linux)	Ctrl, Alt
Return, Delete, Escape	↵ lub Enter, ⌫, Esc
Strzałki	↑ ↓ ← →
Litery	Wielkie: K, nie k

⌘⇧P

Dobrze.Każdy klawisz osobno, w kolejności naciskania, z modyfikatorem danej platformy.

cmd+shift+p

Źle.Całą kombinację w jednym klawiszu albo mieszankę symboli i nazw trudniej odczytać.

Dostępność

Kbd ma znaczenie semantyczne. Renderuje <kbd>, który mówi technologiom wspomagającym, że tekst to dane wprowadzane z klawiatury. Większość czytników ekranu odczytuje symbole takie jak ⌘ („command”); w razie wątpliwości dodaj nazwę ukrytą wizualnie.
Deklaruj skróty na kontrolkach. Widoczna podpowiedź pomaga osobom widzącym; aria-keyshortcuts="Meta+K" na kontrolce informuje wszystkich pozostałych.
Nie przejmuj skrótów platformy. Unikaj jednoliterowych skrótów, które uruchamiają się podczas pisania, i nigdy nie nadpisuj skrótów przeglądarki ani czytnika ekranu.
Kontrast. Tekst klawisza używa muted-foreground, który na powierzchni klawisza osiąga 4,5:1 w obu trybach.

Kbd