Keyboard layout map
Reads which character each physical key makes, so the page can tell the keyboard layout.
In one line
Can learn which keyboard layout you use, such as QWERTY or AZERTY
Reads which character each physical key makes, so the page can tell the keyboard layout.
The layout map shows if the person types on QWERTY, AZERTY, Dvorak or a language specific keyboard. That narrows country and language, and helps shortcuts, but it is also a fingerprint hint.
What it can and can't do
What the user does: Nothing. It happens when the page or app loads
It can
- Check which letter each physical key types
- Guess your country or language from the layout
- Show shortcuts that match your keyboard
It cannot
- See what you type
- Work in Firefox or Safari
- Show a permission pop up; there is none
How it differs between platforms: Chrome, Edge and Samsung Internet support it. Firefox and Safari do not.
Browser support
| Browser | Status | First version | Released | Note |
|---|---|---|---|---|
| Chrome | Supported | 69 | 2018-09-04 | None |
| Edge | Supported | 79 | 2020-01-15 | None |
| Firefox | Not supported | Not available | Not listed | None |
| Safari | Not supported | Not available | Not listed | None |
| Safari on iPhone | Not supported | Not available | Not listed | None |
| Chrome on Android | Supported | 69 | 2018-09-04 | None |
| Samsung Internet | Supported | 10.0 | 2019-08-22 | None |
How a site asks for it
| API | navigator.keyboard.getLayoutMap() |
| Permissions policy | keyboard-map |
| Browser compat keys | api.Keyboard.getLayoutMap |
| How access is granted | none |
| What the user sees | None (no browser prompt) |
| Needs a secure context (HTTPS) | Yes |
| Needs a user gesture | No |
| Activation | none |
| How long it lasts | One-shot per call |
| How to take it back | Nothing to revoke (no permission is stored) |
| Inside an iframe | Permissions Policy keyboard-map (default self); secure context |
Typical flow
- Page calls navigator.keyboard.getLayoutMap()
- Promise resolves with a Map of KeyboardEvent.code to character
- Page compares to known layouts
Data you get
What comes back: Map of key code to produced character
Shape: object
How often: one-shot
| Field | Type | Unit | Range | Precision |
|---|---|---|---|---|
KeyQ | string | None | single character | q on QWERTY, a on AZERTY |
Technical limits
- Chromium only (Chrome 69 and Edge 79); Firefox and Safari do not implement it
- Secure contexts only; no prompt
- Returns about 40 to 50 printable key entries (the alphanumeric block)
- Reflects the active layout; changes fire layoutchange events
- Page in a background tab may get an empty map
The story
What it is
The page can tell which keyboard layout you use, which hints at your country or language.
For you
You see correct key hints in a game, like 'Press Z to jump' on a French keyboard. You do not see that the site learned your layout. It does not ask.
For makers
Games and shortcut heavy apps need to know which key is where. The same info is a quiet clue to country and language, so fraud and ad systems may add it to a browser profile.
Where you see it
| Type | Example | Apps |
|---|---|---|
| games | A browser game shows 'W A S D' hints as 'Z Q S D' for a French player, so controls make sense. | Krunker.io, Shell Shockers |
| creative | A design or music web app maps shortcut keys by physical position, so shortcuts feel right on any layout. | Figma, Soundtrap |
| productivity | A web editor shows the right shortcut label such as the correct slash key on German keyboards. | None named |
| analytics | A fingerprinting script uses the layout as one more clue, together with language and time zone. | None named |
| security | A fraud tool compares the layout with the claimed country, and a mismatch raises suspicion. | None named |
| accessibility | A remapping tool for people with one hand or limited reach uses the layout to build custom shortcuts. | None named |
Risks
- Hints at country and language
- Part of a browser profile
What the platform says
- MDN (standards docs): Keyboard API. Describes a way for web apps to learn which key sits where, so games and editors can show the right key labels.
Good uses and abuse
Legitimate uses
- Show correct shortcut labels
- Games with WASD remapping
Known abuse
- Language and region fingerprinting
Scores
| Score | Value | Meaning |
|---|---|---|
| Sensitivity | 2 of 5 | How revealing the data is |
| Utility | 3 of 5 | How useful it is to honest apps |
| Friction | 0 of 5 | How much the user has to do |
| Fingerprint bits | 3 | Rough identifying entropy, when known |
History
- 2018-09, Chrome 69: Keyboard Map API ships
Related capabilities
Related
- Keyboard and IME events. Can see each key you press while the page has focus
Sources
How well checked: Based on official documentation.