Implementation:Puppeteer Puppeteer USKeyboardLayout

Property	Value
sources	packages/puppeteer-core/src/common/USKeyboardLayout.ts
domains	Input, Keyboard, Device Emulation
last_updated	2026-02-12 00:00 GMT

Overview

Description

USKeyboardLayout is a module that defines the complete US keyboard layout used by Puppeteer's keyboard input simulation. It exports the KeyInput type, the KeyDefinition interface, and the _keyDefinitions constant -- a comprehensive readonly record mapping every valid key input to its corresponding key definition.

The KeyDefinition interface defines the properties of a keyboard key:

• keyCode -- The numeric key code for the key.
• shiftKeyCode -- The key code when Shift is held (for numpad keys).
• key -- The key value string (e.g., 'a', 'Enter').
• shiftKey -- The key value when Shift is held (e.g., 'A', '!').
• code -- The physical key code string (e.g., 'KeyA', 'Digit1').
• text -- The text value to insert (e.g., '\r' for Enter).
• shiftText -- The text value when Shift is held.
• location -- The key location (0=standard, 1=left, 2=right, 3=numpad, 4=mobile).

The KeyInput type is a union of all valid key input strings, encompassing:

• Digit keys ('0'-'9', 'Digit0'-'Digit9')
• Letter keys ('a'-'z', 'A'-'Z', 'KeyA'-'KeyZ')
• Function keys ('F1'-'F24')
• Modifier keys ('ShiftLeft', 'ControlRight', 'Alt', 'Meta', etc.)
• Navigation keys ('ArrowUp', 'Home', 'PageDown', etc.)
• Numpad keys ('Numpad0'-'Numpad9', 'NumpadAdd', etc.)
• Special keys ('Enter', 'Backspace', 'Tab', 'Escape', etc.)
• Symbol keys (';', '=', ',', '-', etc.)
• Media keys ('AudioVolumeMute', 'MediaPlayPause', etc.)
• Mobile keys ('SoftLeft', 'SoftRight', 'Camera', 'Call', etc.)

The _keyDefinitions record contains 180+ key definitions mapping the US keyboard layout.

Usage

This module is used internally by Puppeteer's Keyboard class to translate high-level key names into the low-level key codes, key values, and code values required by the Chrome DevTools Protocol's Input.dispatchKeyEvent method.

Code Reference

Source Location

packages/puppeteer-core/src/common/USKeyboardLayout.ts

Signature

export interface KeyDefinition {
  keyCode?: number;
  shiftKeyCode?: number;
  key?: string;
  shiftKey?: string;
  code?: string;
  text?: string;
  shiftText?: string;
  location?: number;
}

export type KeyInput =
  | '0' | '1' | ... | '9'
  | 'KeyA' | 'KeyB' | ... | 'KeyZ'
  | 'a' | 'b' | ... | 'z'
  | 'A' | 'B' | ... | 'Z'
  | 'F1' | 'F2' | ... | 'F24'
  | 'Enter' | 'Backspace' | 'Tab' | 'Escape'
  | 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown'
  | 'ShiftLeft' | 'ShiftRight' | 'ControlLeft' | 'ControlRight'
  | 'MetaLeft' | 'MetaRight' | 'AltLeft' | 'AltRight'
  | ... ; // 180+ key input values

export const _keyDefinitions: Readonly<Record<KeyInput, KeyDefinition>>;

Import

import {_keyDefinitions, type KeyInput, type KeyDefinition} from './USKeyboardLayout.js';

I/O Contract

Export	Type	Description
KeyDefinition	interface	Describes a keyboard key's properties (keyCode, key, code, text, location, shift variants)
KeyInput	type (string union)	All valid key input values accepted by Keyboard.press and related methods
_keyDefinitions	Readonly<Record<KeyInput, KeyDefinition>>	Complete US keyboard layout mapping key inputs to their definitions

KeyDefinition Property	Type	Description
keyCode	number (optional)	The numeric key code
shiftKeyCode	number (optional)	Key code when Shift is held
key	string (optional)	The key value (e.g., 'a', 'Enter')
shiftKey	string (optional)	Key value when Shift is held (e.g., 'A', '!')
code	string (optional)	Physical key code (e.g., 'KeyA', 'Digit1')
text	string (optional)	Text to insert (e.g., '\r' for Enter)
shiftText	string (optional)	Text to insert when Shift is held
location	number (optional)	Key location: 0=standard, 1=left, 2=right, 3=numpad, 4=mobile

Usage Examples

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');

// Type text using the keyboard (uses USKeyboardLayout internally)
await page.keyboard.type('Hello, World!');

// Press individual keys
await page.keyboard.press('Enter');
await page.keyboard.press('Tab');
await page.keyboard.press('Backspace');

// Use modifier keys
await page.keyboard.down('ShiftLeft');
await page.keyboard.press('KeyA'); // Types 'A'
await page.keyboard.up('ShiftLeft');

// Keyboard shortcuts
await page.keyboard.down('ControlLeft');
await page.keyboard.press('KeyC'); // Ctrl+C
await page.keyboard.up('ControlLeft');

// Function keys
await page.keyboard.press('F5'); // Refresh

// Arrow keys for navigation
await page.keyboard.press('ArrowDown');
await page.keyboard.press('ArrowRight');

await browser.close();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime