Skip to main content

​
Overview

The glide.keys API provides methods for sending keyboard events, capturing key presses, and parsing key notation. This is useful for automating interactions, creating interactive prompts, and building custom key-based workflows.

​
Methods

​
send()

Send a key sequence to the browser, simulating physical key presses. 
glide.keys.send<const Keys>(
  keyseq: string | { glide_key: string },
  opts?: glide.KeySendOptions
): Promise<void>
​
keyseq
string | { glide_key: string }
required
The key sequence to send. Can include:
  • Regular characters: a, b, c, 1, 2, !, @, etc.
  • Special keys: <Space>, <Enter>, <Tab>, <Esc>, <BS>, etc.
  • Arrow keys: <Left>, <Right>, <Up>, <Down>
  • Function keys: <F1>, <F2>, …, <F12>
  • Modifiers: <C-...> (Ctrl), <S-...> (Shift), <A-...> (Alt), <D-...> (Cmd/Super)
  • Leader key: <leader> (expands to glide.g.mapleader, default <Space>)
​
opts.skip_mappings
boolean
If true, send the key events directly to Firefox’s input handler, bypassing all Glide keymaps. Default: false
​
return
Promise<void>
A promise that resolves when all key events have been sent.
Key notation is case-insensitive for special keys: <space>, <Space>, and <SPACE> are all equivalent.

​
next()

Returns a Promise that resolves to a KeyEvent when the next key is pressed. 
glide.keys.next(): Promise<glide.KeyEvent>
​
return
Promise<glide.KeyEvent>
A promise that resolves to a KeyEvent object containing:
  • key: The character representation of the key
  • glide_key: The vim notation of the key (e.g., <C-s>)
  • ctrlKey, shiftKey, altKey, metaKey: Modifier states
  • All standard KeyboardEvent properties
  • Only one Promise can be registered at a time. Calling next() while another is pending will throw an error.
  • This prevents the key from being processed further and does not invoke any associated mappings.
  • Modifier keys alone (Ctrl, Shift, Alt) will not resolve the promise - another key must be pressed.

​
next_str()

Returns a Promise that resolves to a string representation of the next key pressed. 
glide.keys.next_str(): Promise<string>
​
return
Promise<string>
A promise that resolves to the Glide key notation string (e.g., d, <C-l>, <Space>).
This is a convenience wrapper around next() that returns only the glide_key string.

​
next_passthrough()

Capture the next key press without preventing its default behavior. 
glide.keys.next_passthrough(): Promise<glide.KeyEvent>
​
return
Promise<glide.KeyEvent>
A promise that resolves to a KeyEvent object. Unlike next(), the key event continues to be processed normally.
Use next_passthrough() when you want to inspect key presses without interfering with their normal behavior. This is useful for debugging or monitoring.

​
parse()

Parse a single key notation string into a structured object. 
glide.keys.parse(key_notation: string): glide.KeyNotation
​
key_notation
string
required
A single key in Glide notation (e.g., <C-a>, j, <Space>).
​
return
glide.KeyNotation
An object containing:
  • key: The key character or special key name
  • alt: Whether Alt/Option is pressed
  • ctrl: Whether Ctrl is pressed
  • meta: Whether Cmd/Super is pressed
  • shift: Whether Shift is pressed
Special keys are normalized to be consistent. Shifted keys are not special-cased - the returned key is whatever was given in the input.Examples:
  • <Space> → { key: "<Space>" }
  • H → { key: "H" }
  • <S-h> → { key: "h", shift: true }
  • <S-H> → { key: "H", shift: true }

​
Complete Examples

​
Custom Confirmation Prompt

glide.ts
async function confirm(message: string): Promise<boolean> {
  console.log(`${message} (y/n)`);
  const key = await glide.keys.next();
  return key.key === 'y';
}

glide.keymaps.set('normal', '<leader>q', async () => {
  if (await confirm('Close all tabs?')) {
    const tabs = await glide.tabs.query({});
    await browser.tabs.remove(tabs.map(t => t.id!));
  }
});

​
Multi-Key Command

glide.ts
glide.keymaps.set('normal', '<leader>w', async () => {
  console.log('Window command - press h/j/k/l for direction');
  const key = await glide.keys.next();
  
  const directions: Record<string, string> = {
    h: 'left',
    j: 'down',
    k: 'up',
    l: 'right'
  };
  
  const direction = directions[key.key];
  if (direction) {
    console.log(`Splitting window ${direction}`);
    // Implement window splitting logic
  }
});

​
Auto-Type Sequence

glide.ts
glide.keymaps.set('normal', '<leader>at', async () => {
  // Focus an input field first
  // Then type a sequence
  await glide.keys.send('username@example.com');
  await glide.keys.send('<Tab>');
  await glide.keys.send('password123');
  await glide.keys.send('<Enter>');
});

​
Capture and Replay

glide.ts
let recording: string[] = [];
let isRecording = false;

glide.keymaps.set('normal', '<leader>rr', () => {
  isRecording = !isRecording;
  if (isRecording) {
    recording = [];
    console.log('Recording started...');
  } else {
    console.log('Recording stopped.', recording);
  }
});

glide.keymaps.set('normal', '<leader>rp', async () => {
  console.log('Replaying...');
  for (const key of recording) {
    await glide.keys.send(key);
  }
});

glide.autocmds.create('KeyStateChanged', async ({ sequence }) => {
  if (isRecording && sequence.length > 0) {
    recording.push(...sequence);
  }
});

​
Special Key Reference

Basic Keys
  • Letters: a-z, A-Z
  • Numbers: 0-9
  • Symbols: !@#$%^&*()-_=+[]{}\|;:'",./<>?
Special Keys
  • <Space>, <Tab>, <Enter>, <CR>, <Return>
  • <Esc>, <BS>, <Backspace>, <Del>, <Delete>
  • <Insert>
Navigation
  • <Up>, <Down>, <Left>, <Right>
  • <Home>, <End>
  • <PageUp>, <PgUp>, <PageDown>, <PgDn>
Function Keys
  • <F1> through <F12>
Modifiers
  • <C-...>: Ctrl
  • <S-...>: Shift
  • <A-...>: Alt/Option
  • <M-...>: Alt/Option (alias)
  • <D-...>: Cmd/Super
Number Pad
  • <k0> through <k9>
  • <kPlus>, <kMinus>, <kMultiply>, <kDivide>
  • <kEnter>, <kPoint>
Media Keys
  • <AudioVolumeUp>, <AudioVolumeDown>, <AudioVolumeMute>
  • <MediaPlayPause>, <MediaStop>, <MediaTrackNext>, <MediaTrackPrevious>
Browser Keys
  • <BrowserBack>, <BrowserForward>, <BrowserRefresh>
  • <BrowserStop>, <BrowserSearch>, <BrowserFavorites>, <BrowserHome>
Misc
  • <leader>: Expands to glide.g.mapleader (default <Space>)
  • <lt>: Literal < character
  • <Bar>: Literal | character
  • <Bslash>: Literal \ character

​
Type Reference

​
glide.KeyEvent

type KeyEvent = KeyboardEvent & {
  glide_key: string; // e.g., '<C-s>', 'j', '<Space>'
};

​
glide.KeyNotation

type KeyNotation = {
  key: string;
  alt: boolean;
  ctrl: boolean;
  meta: boolean;
  shift: boolean;
};

​
glide.KeySendOptions

type KeySendOptions = {
  skip_mappings?: boolean;
};