Core Concepts

Keyboard Input

Simulate keyboard input to type text, press keys, and trigger keyboard shortcuts in your automation scripts.

Try it out

Watch as text is typed character by character

Shift

Input Field

Code

typescript

import { keyboard } from "@nut-tree/nut-js";

// Type a string character by character
await keyboard.type("Hello, nut.js!");

What you can do

Type Text

Type strings of text character by character

keyboard.type("Hello World")

Press Keys

Press and release individual keys or key combinations

keyboard.type(Key.Enter)

Keyboard Shortcuts

Trigger shortcuts like Ctrl+C, Cmd+V, Alt+Tab

keyboard.type(Key.LeftControl, Key.C)

Hold Keys

Press and hold keys for drag operations or gaming

keyboard.pressKey(Key.LeftShift)

Configurable Speed

Control typing speed with configurable delays

keyboard.config.autoDelayMs = 100

Cross-Platform

Works on Windows, macOS, and Linux

// Same API everywhere

Quick Reference

type

keyboard.type(...input: (string | Key)[])

Promise<void>

Type text or press keys. Accepts strings and Key enum values.

pressKey

keyboard.pressKey(...keys: Key[])

Promise<void>

Press and hold one or more keys. Must be released with releaseKey.

releaseKey

keyboard.releaseKey(...keys: Key[])

Promise<void>

Release one or more keys that were previously pressed.

Full API Reference

View complete keyboard module documentation with all methods and options

Typing Text

The type method is the primary way to simulate keyboard input. It can type strings of text or press individual keys.

Typing Strings

Type a string of text character by character:

typescript

import { keyboard } from "@nut-tree/nut-js";

// Type a simple string
await keyboard.type("Hello, World!");

// Type unicode characters
await keyboard.type("nut.js rocks! 🚀✨");

Typing Keys

Press individual keys using the Key enum:

typescript

import { keyboard, Key } from "@nut-tree/nut-js";

// Press Enter
await keyboard.type(Key.Enter);

// Press Escape
await keyboard.type(Key.Escape);

// Press Tab
await keyboard.type(Key.Tab);

// Press arrow keys
await keyboard.type(Key.Up);
await keyboard.type(Key.Down);
await keyboard.type(Key.Left);
await keyboard.type(Key.Right);

Keyboard Shortcuts

Trigger keyboard shortcuts by passing multiple keys to type. The keys are pressed simultaneously, simulating a keyboard shortcut.

typescript

import { keyboard, Key } from "@nut-tree/nut-js";

// Copy (Ctrl+C / Cmd+C)
await keyboard.type(Key.LeftControl, Key.C);  // Windows/Linux
await keyboard.type(Key.LeftSuper, Key.C);    // macOS

// Paste (Ctrl+V / Cmd+V)
await keyboard.type(Key.LeftControl, Key.V);  // Windows/Linux
await keyboard.type(Key.LeftSuper, Key.V);    // macOS

// Select All (Ctrl+A / Cmd+A)
await keyboard.type(Key.LeftControl, Key.A);

// Undo (Ctrl+Z / Cmd+Z)
await keyboard.type(Key.LeftControl, Key.Z);

// Save (Ctrl+S / Cmd+S)
await keyboard.type(Key.LeftControl, Key.S);

// Open Spotlight on macOS
await keyboard.type(Key.LeftSuper, Key.Space);

// Alt+Tab to switch windows
await keyboard.type(Key.LeftAlt, Key.Tab);

// Alt+F4 to close window (Windows)
await keyboard.type(Key.LeftAlt, Key.F4);

Platform-Specific Shortcuts

Use Key.LeftSuper for the Command key on macOS or the Windows key on Windows. This allows you to write cross-platform scripts that work on all platforms.

Press and Hold Keys

For more control over key states, use pressKey and releaseKey. This is useful for holding modifier keys during mouse operations or gaming scenarios.

typescript

import { keyboard, Key } from "@nut-tree/nut-js";

// Hold Shift while clicking (for multi-select)
await keyboard.pressKey(Key.LeftShift);
// ... perform mouse clicks here ...
await keyboard.releaseKey(Key.LeftShift);

// Hold Ctrl while clicking (for non-contiguous select)
await keyboard.pressKey(Key.LeftControl);
// ... perform mouse clicks here ...
await keyboard.releaseKey(Key.LeftControl);

// Press and release Alt+F4
await keyboard.pressKey(Key.LeftAlt, Key.F4);
await keyboard.releaseKey(Key.LeftAlt, Key.F4);

Holding Keys

While it is possible to use pressKey and releaseKey with any Key, it actually only makes sense to use them with modifier keys like Key.LeftShift. There's no automatic key repeat when pressing and holding e.g. Key.A. If you want to simulate key repeat, you can use keyboard.type with setInterval instead.

Always Release Keys

Make sure to release any keys you press with pressKey. Unreleased keys will remain "stuck" until released, which can cause unexpected behavior in your system.

Configuration

Configure keyboard behavior using the keyboard.config object.

typescript

import { keyboard } from "@nut-tree/nut-js";

// Set delay between keystrokes (in milliseconds)
keyboard.config.autoDelayMs = 100;

// Type slowly (100ms between each character)
await keyboard.type("Typing slowly...");

// Type faster
keyboard.config.autoDelayMs = 10;
await keyboard.type("Typing quickly!");

// No delay (instant)
keyboard.config.autoDelayMs = 0;
await keyboard.type("Instant typing");

Default Delay

The default autoDelayMs value provides a balance between speed and reliability. Some applications may miss keystrokes if typing is too fast.

Key Reference

The Key enum provides constants for all keyboard keys. Here are the most commonly used keys:

Modifier Keys

typescript

// Shift
Key.LeftShift, Key.RightShift

// Control
Key.LeftControl, Key.RightControl

// Alt / Option
Key.LeftAlt, Key.RightAlt

// Super (Windows key / Command key)
Key.LeftSuper, Key.RightSuper

Special Keys

typescript

// Navigation
Key.Enter, Key.Tab, Key.Escape, Key.Space
Key.Backspace, Key.Delete
Key.Home, Key.End, Key.PageUp, Key.PageDown

// Arrow Keys
Key.Up, Key.Down, Key.Left, Key.Right

// Function Keys
Key.F1, Key.F2, Key.F3, Key.F4, Key.F5, Key.F6
Key.F7, Key.F8, Key.F9, Key.F10, Key.F11, Key.F12

Real-World Examples

Here are practical examples showing how to use keyboard input in real automation scenarios.

Open Application via Spotlight (macOS)

Use Spotlight to quickly open an application

Scenario: You want to open Calculator on macOS without knowing its exact location.

typescript

import { keyboard, Key } from "@nut-tree/nut-js";

// Open Spotlight
await keyboard.type(Key.LeftSuper, Key.Space);

// Wait for Spotlight to appear
await new Promise(r => setTimeout(r, 500));

// Type application name
await keyboard.type("calculator");

// Press Enter to open
await keyboard.type(Key.Enter);

Fill a Form

Navigate and fill form fields using Tab and typing

Scenario: You need to fill out a form with multiple fields.

typescript

import { keyboard, Key } from "@nut-tree/nut-js";

// Assuming first field is focused
await keyboard.type("John Doe");

// Tab to next field (email)
await keyboard.type(Key.Tab);
await keyboard.type("john@example.com");

// Tab to next field (phone)
await keyboard.type(Key.Tab);
await keyboard.type("555-1234");

// Tab to submit button and press Enter
await keyboard.type(Key.Tab);
await keyboard.type(Key.Enter);

Copy and Paste Text

Select all text, copy it, and paste elsewhere

Scenario: You want to copy content from one application and paste it into another.

typescript

import { keyboard, Key } from "@nut-tree/nut-js";

// Select all text
await keyboard.type(Key.LeftControl, Key.A);

// Copy selected text
await keyboard.type(Key.LeftControl, Key.C);

// Switch to another window
await keyboard.type(Key.LeftAlt, Key.Tab);
await new Promise(r => setTimeout(r, 300));

// Paste text
await keyboard.type(Key.LeftControl, Key.V);

Hold Shift for Multi-Select

Select multiple items by holding Shift while clicking

Scenario: You want to select a range of files in a file manager.

typescript

import { keyboard, mouse, straightTo, Point, Key, Button } from "@nut-tree/nut-js";

// Click first item
await mouse.move(straightTo(new Point(200, 100)));
await mouse.click(Button.LEFT);

// Hold Shift and click last item to select range
await keyboard.pressKey(Key.LeftShift);
await mouse.move(straightTo(new Point(200, 300)));
await mouse.click(Button.LEFT);
await keyboard.releaseKey(Key.LeftShift);

// All items between first and last are now selected

Important Notes

Concurrent Input Sequences

If you interleave multiple keyboard input sequences (e.g., from parallel async operations), it is not guaranteed that their input sequences won't be mixed up. This is similar to how multiple physical keyboards would compete for input on a single machine.

Best Practices

Use appropriate delays between operations for reliability
Always release keys that you press with pressKey
Test your scripts on the target system to ensure compatibility
Consider using image search to verify UI state before typing