edtui 0.11.2

EdTUI

Overview

EdTUI is a text editor widget for the Ratatui ecosystem. It is designed to provide a user experience inspired by Vim. Edtui is developed to be used as an editor in ratatui apps. It is not supposed to be a stand-alone code editor.

Create a new EditorState and render it using EditorView. You can customize the theme, enable line wrapping, syntax highlight the text or set the tab width:

use edtui::{EditorState, EditorTheme, EditorView};
use ratatui::widgets::Widget;

let mut state = EditorState::default();
EditorView::new(&mut state)
        .theme(EditorTheme::default())
        .wrap(true)
        .syntax_highlighter(None)
        .tab_width(2)
        .render(area, buf);

Handle events (Vim mode by default):

use edtui::EditorEventHandler;

let mut event_handler = EditorEventHandler::default();
event_handler.on_key_event(key_event, &mut state);

Or use Emacs mode (modeless editing):

use edtui::{EditorState, EditorEventHandler, Lines};

let mut state = EditorState::new(Lines::from("Hello World"));
let mut event_handler = EditorEventHandler::emacs_mode();
event_handler.on_key_event(key_event, &mut state);

Or customize keybindings:

let mut key_handler = KeyEventHandler::vim_mode();
key_handler.insert(
    KeyEventRegister::n(vec![KeyInput::ctrl('x')]),
    SwitchMode(EditorMode::Insert),
);
let event_handler = EditorEventHandler::new(key_handler);

Demo

Features

• Custom theming.
• Mouse events.
• Vim and Emacs keybindings.
• Copy paste using the systems clipboard.
• Line wrapping.
• Syntax highlighting.
• Line numbers (absolute and relative).
• System editor support (optional, via system-editor feature).

Theming

Customize the editor EditorTheme:

use edtui::{EditorTheme, EditorStatusLine};
use ratatui::style::{Style, Color};
use ratatui::widgets::Block;

let theme = EditorTheme::default()
    .block(Block::default())
    .base(Style::default().bg(Color::Black).fg(Color::White))
    .cursor_style(Style::default().bg(Color::White).fg(Color::Black))
    .selection_style(Style::default().bg(Color::Yellow).fg(Color::Black))
    .hide_status_line(); // or use `.status_line(..)` for styling the status line

Line Numbers

Display absolute or relative line numbers:

use edtui::{EditorView, EditorState, EditorTheme, LineNumbers};
use ratatui::style::{Style, Color};

EditorView::new(&mut EditorState::default())
        .theme(EditorTheme::default().line_numbers_style(Style::default().fg(Color::DarkGray)))
        .line_numbers(LineNumbers::Absolute)  // or LineNumbers::Relative
        .render(area, buf);

Single-Line Mode

For search boxes and single-line input fields, enable single-line mode to block newline insertion:

use edtui::{EditorState, EditorView};

let mut state = EditorState::default();
EditorView::new(&mut state)
        .single_line(true)
        .render(area, buf);

When enabled, newline insertion is blocked and pasting text with newlines will replace them with spaces.

Mouse Events

Edtui supports mouse input for moving the cursor and selecting text. Mouse handling is enabled by default via a feature toggle. Typically, mouse events are processed automatically when you call on_event:

let event_handler = EditorEventHandler::default();
event_handler.on_event(event, &mut state); // handles mouse events too

If you want finer control you can handle mouse events explicitly using on_mouse_event:

event_handler.on_mouse_event(mouse_event, &mut state);

Syntax highlighting

Syntax highlighting was added in version 0.8.4.

Edtui offers a number of custom themes, see [SyntaxHighlighter::theme] for a complete list. If you want to use a custom theme, see [SyntaxHighlighter::custom_theme]. Check syntect for more details about themes and extensions.

use edtui::{EditorView, EditorState, SyntaxHighlighter};

let syntax_highlighter = SyntaxHighlighter::new("dracula", "rs");
EditorView::new(&mut EditorState::default())
        .syntax_highlighter(Some(syntax_highlighter))
        .render(area, buf);

Paste Support

If you want to enable paste (via ctrl+y or cmd+y) you must explicitly enable it at the start of your app:

use ratatui::crossterm::event::EnableBracketedPaste;
let mut stdout = std::io::stdout();
ratatui::crossterm::xecute!(stdout, EnableBracketedPaste);

and disable it during cleanup:

use ratatui::crossterm::event::DisableBracketedPaste;
ratatui::crossterm::execute!(std::io::stdout(), DisableBracketedPaste);

See examples/app/term.rs for a an example.

System Editor

With the system-editor feature enabled you can open the editor content in an external text editor (e.g., nvim) using Ctrl+e in normal mode (or Alt+e in Emacs mode).

The system editor is decoupled from the event handler. After handling events, check if a system editor request is pending and call open yourself:

use edtui::system_editor;

event_handler.on_event(event, &mut state);

if system_editor::is_pending(&state) {
    system_editor::open(&mut state, &mut terminal)?;
    // Re-enable mouse capture or other terminal modes if necessary
    // crossterm::execute!(stdout(), EnableMouseCapture, EnableBracketedPaste)?;
}

The editor used is determined by the VISUAL or EDITOR environment variables, falling back to a platform-specific default if neither is set.

Keybindings

EdTUI offers Vim keybindings by default and Emacs keybindings as an alternative.

Vim Mode (default)

Normal Mode:

Insert Mode:

Emacs Mode

Emacs Mode was added in version 0.10.1.

Note that Emacs Mode is less feature complete and less tested than vim mode.

Roadmap

• Support termwiz and termion

License: MIT