vim-navigator

Vim-style modal editing and navigation patterns for Ratatui TUIs.

Features

• Modal editing with Normal, Insert, and Command modes
• Vim keybindings (j/k, g/G, :commands, etc.)
• List navigation with automatic bounds checking
• Zero runtime dependencies beyond crossterm

Usage

Add to your Cargo.toml:

[dependencies]
vim-navigator = "0.1"
crossterm = "0.28"

Basic example:

use vim_navigator::{VimNavigator, ListNavigator, NavAction, InputMode};
use crossterm::event::{self, Event, KeyEvent};

struct App {
    vim_nav: VimNavigator,
    items: Vec<String>,
    items_nav: ListNavigator,
}

impl App {
    fn handle_input(&mut self, key: KeyEvent) -> bool {
        match self.vim_nav.handle_key(key) {
            NavAction::Quit => return true,
            NavAction::MoveDown => self.items_nav.move_down(self.items.len()),
            NavAction::MoveUp => self.items_nav.move_up(),
            NavAction::MoveTop => self.items_nav.move_top(),
            NavAction::MoveBottom => self.items_nav.move_bottom(self.items.len()),
            NavAction::Command(cmd) => self.execute_command(&cmd),
            NavAction::ModeChange(_) => {},
            _ => {}
        }
        false
    }

    fn execute_command(&mut self, cmd: &str) {
        match cmd {
            "q" | "quit" => std::process::exit(0),
            _ => {}
        }
    }
}

Keybindings

Normal Mode

• j / Down - Move down
• k / Up - Move up
• g - Jump to top
• G - Jump to bottom
• : - Enter command mode
• i - Enter insert mode
• q - Quit (returns NavAction::Quit)

Command Mode

• Type commands after :
• Enter - Execute command
• Esc - Cancel and return to normal mode
• Backspace - Delete character

Insert Mode

• Esc - Return to normal mode
• All other keys return NavAction::None for app-specific handling

License

MIT OR Apache-2.0