vim.motion - Cursor Motion API

Programmatic cursor movement primitives. Useful for plugins like smear-cursor that need smooth cursor animations.

Basic Movements

Directional Motion

// Move cursor like pressing h/j/k/l
vim.motion.left();   // Like 'h'
vim.motion.down();   // Like 'j'
vim.motion.up();     // Like 'k'
vim.motion.right();  // Like 'l'

Line Motion

// Move within current line
vim.motion.lineStart();     // Like '0' - go to column 0
vim.motion.lineEnd();       // Like '$' - go to end of line
vim.motion.firstNonBlank(); // Like '^' - first non-whitespace

Word Motion

// Word-wise navigation
vim.motion.wordForward();   // Like 'w' - next word start
vim.motion.wordBackward();  // Like 'b' - previous word start
vim.motion.wordEnd();       // Like 'e' - end of word

File Navigation

// Jump to file boundaries
vim.motion.fileStart();  // Like 'gg' - first line
vim.motion.fileEnd();    // Like 'G' - last line

// Jump to specific line (0-indexed)
vim.motion.gotoLine(99); // Go to line 100

Use Cases

Smooth Cursor Animation Plugin

// Animate cursor from current position to target
function animateCursor(targetLine: number, targetCol: number) {
  const start = vim.cursor.getPosition();
  const steps = 10;

  for (let i = 1; i <= steps; i++) {
    const t = i / steps;
    const row = Math.round(start.row + (targetLine - start.row) * t);
    const col = Math.round(start.col + (targetCol - start.col) * t);

    vim.cursor.setRenderPosition(row, col);
    // Wait for animation frame...
  }

  vim.cursor.clearRenderPosition();
}

// Now move the actual cursor
vim.motion.gotoLine(targetLine);

Programmatic Navigation

// Navigate like typing 'jjjww'
vim.motion.down();
vim.motion.down();
vim.motion.down();
vim.motion.wordForward();
vim.motion.wordForward();

Custom Movement Command

vim.api.createUserCmd('CenterLine', () => {
  // Move to middle of file
  const lineCount = vim.api.bufLineCount(0);
  vim.motion.gotoLine(Math.floor(lineCount / 2));
}, { desc: 'Jump to middle of file' });

Function Reference

See Also

• vim.cursor - Cursor render position for animations
• vim.api - Window cursor functions (winGetCursor, winSetCursor)
• vim.keymap - Create motion keybindings