Crate vimltui 

vimltui

A self-contained, embeddable Vim editor for Ratatui TUI applications.

vimltui provides a fully functional Vim editing experience that you can drop into any Ratatui-based terminal application. Each VimEditor instance owns its own text buffer, cursor, mode, undo/redo history, search state, and registers — completely independent from your application state.

Features

• Normal / Insert / Visual modes (Char, Line, Block)
• Operator + Motion composition (dw, ci", y$, >j, gUw, …)
• f / F / t / T character find motions
• Search with /, ?, n, N and match highlighting
• Dot repeat (.) for last edit
• Undo / Redo with snapshot stack
• Command mode (:w, :q, :wq, :123)
• Registers and system clipboard integration
• Text objects (iw, i", i()
• Relative line numbers in the built-in renderer
• Pluggable syntax highlighting via the SyntaxHighlighter trait

Quick Start

use vimltui::{VimEditor, VimModeConfig};

// Create an editor with full editing capabilities
let mut editor = VimEditor::new("Hello, Vim!", VimModeConfig::default());

// Create a read-only viewer (visual selection only, no insert)
let mut viewer = VimEditor::new("Read only content", VimModeConfig::read_only());

// Get the current content back
let text = editor.content();

Handling Input

use vimltui::{VimEditor, VimModeConfig, EditorAction};
use crossterm::event::KeyEvent;

let mut editor = VimEditor::new("", VimModeConfig::default());

// In your event loop:
// let action = editor.handle_key(key_event);
// match action {
//     EditorAction::Handled => { /* editor consumed the key */ }
//     EditorAction::Unhandled(key) => { /* pass to your app's handler */ }
//     EditorAction::Save => { /* user typed :w */ }
//     EditorAction::Close => { /* user typed :q */ }
//     EditorAction::ForceClose => { /* user typed :q! */ }
//     EditorAction::SaveAndClose => { /* user typed :wq */ }
// }

Rendering

Use the built-in renderer with your own SyntaxHighlighter:

use vimltui::{VimTheme, PlainHighlighter, SyntaxHighlighter};
use ratatui::style::Color;
use ratatui::text::Span;

// Built-in PlainHighlighter for no syntax coloring
let highlighter = PlainHighlighter;

// Or implement your own:
struct SqlHighlighter;
impl SyntaxHighlighter for SqlHighlighter {
    fn highlight_line<'a>(&self, line: &'a str, spans: &mut Vec<Span<'a>>) {
        spans.push(Span::raw(line));
    }
}

Re-exports

pub use editor::VimEditor;

Modules

editor

render

Structs

EditRecord

Recorded keystrokes for dot-repeat (.).

MotionRange

The range affected by a motion, used by operators.

PlainHighlighter

No-op highlighter — renders text without any syntax coloring.

Register

Register content (for yank/paste).

SearchState

State for incremental search (/ and ?).

Snapshot

Snapshot of editor state for undo/redo.

VimModeConfig

Configures which Vim modes are available in an editor instance.

VimTheme

Theme colors used by the built-in render module.

YankHighlight

Temporary highlight for yanked text (like Neovim’s vim.highlight.on_yank()).

Enums

CursorShape

Cursor shape hint for renderers.

EditorAction

Actions returned from VimEditor::handle_key() to inform the parent application.

FindDirection

Direction for f/F/t/T character find motions.

Operator

Operator waiting for a motion (e.g., d waits for w → dw).

VimMode

Vim editing mode.

VisualKind

Visual selection kind.

Constants

LEADER_KEY

Leader key (space by default, like modern Neovim setups).

SCROLLOFF

Number of lines kept visible above/below the cursor when scrolling.

Traits

SyntaxHighlighter

Trait for language-specific syntax highlighting.