Skip to Content
Platform.Ontology

Keyboard layout map

Reads which character each physical key makes, so the page can tell the keyboard layout.

Works without askingTyping and clipboardTextWeb browsersWhile you use it

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

BrowserStatusFirst versionReleasedNote
ChromeSupported692018-09-04None
EdgeSupported792020-01-15None
FirefoxNot supportedNot availableNot listedNone
SafariNot supportedNot availableNot listedNone
Safari on iPhoneNot supportedNot availableNot listedNone
Chrome on AndroidSupported692018-09-04None
Samsung InternetSupported10.02019-08-22None

How a site asks for it

APInavigator.keyboard.getLayoutMap()
Permissions policykeyboard-map
Browser compat keysapi.Keyboard.getLayoutMap
How access is grantednone
What the user seesNone (no browser prompt)
Needs a secure context (HTTPS)Yes
Needs a user gestureNo
Activationnone
How long it lastsOne-shot per call
How to take it backNothing to revoke (no permission is stored)
Inside an iframePermissions Policy keyboard-map (default self); secure context

Typical flow

  1. Page calls navigator.keyboard.getLayoutMap()
  2. Promise resolves with a Map of KeyboardEvent.code to character
  3. Page compares to known layouts

Data you get

What comes back: Map of key code to produced character
Shape: object
How often: one-shot

FieldTypeUnitRangePrecision
KeyQstringNonesingle characterq 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

TypeExampleApps
gamesA 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
creativeA design or music web app maps shortcut keys by physical position, so shortcuts feel right on any layout.Figma, Soundtrap
productivityA web editor shows the right shortcut label such as the correct slash key on German keyboards.None named
analyticsA fingerprinting script uses the layout as one more clue, together with language and time zone.None named
securityA fraud tool compares the layout with the claimed country, and a mismatch raises suspicion.None named
accessibilityA 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

Good uses and abuse

Legitimate uses

  • Show correct shortcut labels
  • Games with WASD remapping

Known abuse

  • Language and region fingerprinting

Scores

ScoreValueMeaning
Sensitivity2 of 5How revealing the data is
Utility3 of 5How useful it is to honest apps
Friction0 of 5How much the user has to do
Fingerprint bits3Rough identifying entropy, when known

History

  • 2018-09, Chrome 69: Keyboard Map API ships

Sources

How well checked: Based on official documentation.

On this page