Użytkownik naciska Escape, a modal się nie zamyka. Naciska Enter w polu wyszukiwania i nic. Znajome? Obsługa klawiatury w JavaScript wydaje się prosta, dopóki nie zacznie się Pan/Pani zagłębiać w trzy zdarzenia, dziesięć właściwości i zoo różnic między przeglądarkami.

Każdy keydown lub keyup generuje obiekt KeyboardEvent z dwoma tuzinami pól. Część z nich jest przestarzała od czasów IE, część zachowuje się inaczej w Firefox i Chrome. A dokumentacja MDN roi się od uwag „nie używać". Deweloper nie potrzebuje kolejnej specyfikacji, lecz ściągawki, która działa.

Poniżej pełny przewodnik po zdarzeniach klawiaturowych: od anatomii KeyboardEvent po gotowe snippety dla skrótów klawiszowych. Tabelę kodów proszę trzymać w zakładkach, przyda się w co drugim projekcie.

💡 Szybki przegląd:

• Proszę używać keydown zamiast keypress: działa dla dowolnych klawiszy.
• event.key podaje znak klawisza, event.code zwraca jego fizyczny kod.
• event.keyCode oraz event.which są przestarzałe, w nowym kodzie proszę ich nie stosować.
• W tabeli poniżej zebrano kody wszystkich standardowych klawiszy dla współczesnych przeglądarek.

Co znajduje się wewnątrz KeyboardEvent

Gdy użytkownik naciska dowolny klawisz, przeglądarka tworzy obiekt KeyboardEvent, potomka UIEvent, który z kolei rozszerza bazowy Event. Wewnątrz znajdują się właściwości samego klawisza, stan modyfikatorów, informacja o układzie klawiatury.

Specyfikacja UI Events ewoluuje: pojawiają się nowe właściwości, starsze przechodzą do statusu deprecated. Główna zmiana ostatnich lat to odejście od kodów numerycznych (keyCode / charCode / which) na rzecz event.key oraz event.code. Wszystkie współczesne przeglądarki wspierają tę parę i to na nich należy opierać logikę.

Wsparcie przeglądarek jest praktycznie pełne: Chrome 51+, Firefox 29+, Safari 10.1+, Edge 79+. Jeśli Pana/Pani projekt nie trzyma się IE11, można zapomnieć o event.which.

Trzy zdarzenia: keydown, keypress i keyup

Przeglądarka rozróżnia trzy zdarzenia klawiaturowe. Kolejność wyzwalania jest stała:

• keydown, klawisz został naciśnięty (moment dotknięcia);
• keypress, klawisz jest przytrzymywany i generuje znak (tylko dla klawiszy znakowych);
• keyup, klawisz został zwolniony.

Subskrypcja keydown przez addEventListener:

1
const input = document.getElementById('type-here');
2
 
3
input.addEventListener('keydown', function (event) {
4
  console.log('Нажата:', event.key, '| Код:', event.code);
5
});

Dla obsługi inline, atrybut elementu:

1
<input type="text" id="type-here" onkeyup="handleKey(event)">

Jeśli wyświetli Pan/Pani obiekt zdarzenia w konsoli, zobaczy Pan/Pani pełną strukturę ze wszystkimi odziedziczonymi polami z UIEvent i Event:

Dlaczego keydown jest głównym wyborem

keypress został oficjalnie uznany za przestarzały. Wyzwala się tylko dla klawiszy, które generują wartość znakową, i nie przechwytuje modyfikatorów: ani Alt, ani Ctrl, ani Shift, ani Meta. Ctrl+Z lub Shift+Tab przez keypress nie da się obsłużyć.

Różnica między keydown a keyup: keydown wyzwala się przed przetworzeniem klawisza przez przeglądarkę; keyup wyzwala się po. Stąd ważna konsekwencja: event.preventDefault() wewnątrz keydown anuluje działanie przeglądarki (na przykład wprowadzenie znaku w pole), a wewnątrz keyup już nie. Dla skrótów klawiszowych, walidacji wprowadzania i sterowania w grach potrzebny jest właśnie keydown.

Tabela właściwości KeyboardEvent

Trzy dolne wiersze są deprecated. Wszędzie, gdzie to możliwe, proszę przechodzić na event.key. Jeśli musi Pan/Pani wspierać starą przeglądarkę, proszę zrobić fallback:

1
window.addEventListener('keydown', function (event) {
2
  const key = event.key !== undefined ? event.key : event.which;
3
  if (key !== undefined) {
4
    console.log('Клавиша:', key);
5
  }
6
});

Ale w 2026 roku taki kod jest tylko dla projektów legacy. event.key działa wszędzie.

Klawisze modyfikujące i kombinacje

Klawisze Control, Shift, Alt i Meta same w sobie nie wykonują akcji, ale zmieniają zachowanie innych klawiszy. Naciśnięcie Z daje literę „z", a Ctrl+Z wykonuje cofnięcie akcji.

Śledzenie modyfikatora umożliwiają właściwości logiczne zdarzenia:

1
document.getElementById('editor').addEventListener('keydown', function (event) {
2
  if (event.ctrlKey && event.key === 'z') {
3
    event.preventDefault();
4
    undoAction();
5
  }
6
 
7
  if (event.ctrlKey && event.shiftKey && event.key === 'z') {
8
    event.preventDefault();
9
    redoAction();
10
  }
11
});

To samo podejście stosuje się dla dowolnych kombinacji: Ctrl+S (zapisz), Ctrl+Shift+N (nowe okno), Alt+Tab (przełączanie). Kolejność sprawdzania: najpierw modyfikatory przez flagi logiczne, potem event.key dla konkretnego klawisza. Dzięki temu logika jest czytelna, a nie tonie w kodach numerycznych.

Pełna tabela kodów klawiszy

Poniżej aktualna tabela dla wszystkich standardowych klawiszy. Wartości event.key oraz event.code podano tak, jak zwracają je współczesne przeglądarki (Chrome, Firefox, Edge, Safari).

Nawigacja i akcje

Rząd cyfr (główna klawiatura)

Litery A-Z

event.key zwraca wartość małymi literami dla liter. event.code nie zależy od wielkości liter ani układu klawiatury: KeyA oznacza fizyczny klawisz A, nawet jeśli układ jest polski i wprowadzane jest „A".

Klawisze specjalne

Klawiatura numeryczna (Numpad)

Klawisze funkcyjne

Systemowe i multimedialne

Znaki interpunkcyjne i symbole

Ważne uwagi do tabeli

• event.which to właściwość przestarzała, proszę używać event.key.
• event.code jest taki sam dla małej (a) i dużej (A) litery, jest to fizyczny klawisz. event.key zwraca faktyczny znak z uwzględnieniem wielkości liter.
• W Firefox wartości event.which dla klawiszy Equal, Semicolon i Minus różnią się od Chrome/Edge/Safari (wskazano w uwagach). Kolejny powód, by nie używać event.which.
• Przeglądarki oparte na Chromium i Firefox dają takie same event.key oraz event.code dla wszystkich wymienionych klawiszy.
• Klawiatury wirtualne: specyfikacja UI Events wymaga, aby klawiatura wirtualna (mobilna, ekranowa), która odwzorowuje układ standardowej, zwracała poprawne event.code. W praktyce przeglądarki mobilne (Chrome Android, Safari iOS) poprawnie obsługują keydown/keyup dla głównych klawiszy, ale event.code może być pusty dla niestandardowych układów.

Interaktywny trener

Do szybkiego sprawdzenia dowolnego kodu z artykułu proszę użyć trenera klawiaturowego: keyevents.netlify.app. Proszę najechać kursorem na obszar, naciskać klawisze i obserwować wartości event.key, event.code i event.which, a także stan flag modyfikatorów w czasie rzeczywistym. Kod źródłowy dostępny na GitHub.

Wideo: zdarzenia klawiaturowe w praktyce

Krótka praktyczna analiza keydown i keyup, działania modyfikatorów i skrótów klawiszowych z żywymi przykładami:

⁉️🤔 Często zadawane pytania

Czym event.key różni się od event.code?

event.key zwraca wartość znakową z uwzględnieniem układu klawiatury i wielkości liter: dla klawisza A jest to "a" (lub "A" z Shift), dla polskiego układu, "ф". event.code zwraca fizyczny kod klawisza, taki sam dla wszystkich układów: "KeyA". Dla skrótów klawiszowych pewniejsze jest event.code, nie zależy on od języka wprowadzania. Do wprowadzania tekstu proszę używać event.key.

Dlaczego keypress nie jest już używane?

Specyfikacja W3C oznaczyła keypress jako przestarzałe: wyzwala się tylko dla klawiszy znakowych i nie przechwytuje modyfikatorów. Ctrl+C, Shift+Tab i innych kombinacji przez keypress nie da się obsłużyć. keydown obejmuje wszystkie klawisze i jest wspierane jednolicie we wszystkich współczesnych przeglądarkach.

Czy można całkowicie zrezygnować z event.which i event.keyCode?

Tak, w 2026 roku można. event.key jest wspierane przez Chrome 51+, Firefox 29+, Safari 10.1+, Edge 79+. Jeśli Pana/Pani projekt nie celuje w IE11 lub Firefox 28, proszę używać tylko event.key i event.code.

Jak obsłużyć długie przytrzymanie klawisza?

Proszę połączyć keydown i keyup. Przy keydown proszę uruchomić timer lub requestAnimationFrame, przy keyup zresetować. Dla sterowania w grach to standardowy wzorzec: klawisz wciśnięty, postać się porusza, zwolniony, zatrzymuje się.

Czy zdarzenia klawiaturowe działają na urządzeniach mobilnych?

keydown i keyup działają w przeglądarkach mobilnych przy użyciu zewnętrznej klawiatury Bluetooth. Klawiatura ekranowa generuje zdarzenia input, a nie keydown/keyup dla wszystkich klawiszy, dlatego dla pól tekstowych na urządzeniach mobilnych lepiej używać zdarzenia input.

Jak odróżnić lewy Shift od prawego?

Przez event.code: "ShiftLeft" lub "ShiftRight". event.key dla obu zwraca "Shift". Analogicznie dla Control, Alt i Meta.

Co stosować w Pana/Pani projekcie

Jeśli pisze Pan/Pani nowy kod, proszę brać keydown jako główne zdarzenie, a do identyfikacji klawiszy event.key (znak) i event.code (fizyczny klawisz). To połączenie pokrywa wszystkie scenariusze: skróty klawiszowe, nawigację, sterowanie w grach, walidację formularzy.

Jeśli wspiera Pan/Pani produkt z kodem legacy na event.which lub event.keyCode, proszę zaplanować refaktoring. Zakres prac jest niewielki: wymiana w handlerach, a zysk to czysty, przewidywalny kod bez zoo różnic między przeglądarkami.

Proszę trzymać powyższą tabelę w zakładkach. Gdy następnym razem będzie Pan/Pani potrzebować kodu konkretnego klawisza, proszę otworzyć i skopiować odpowiednią wartość event.code, nie wspominając kodów numerycznych z epoki IE6.