edtui 0.10.6

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:

use edtui::{KeyEventHandler, KeyEventRegister, EditorEventHandler};

let mut key_handler = KeyEventHandler::vim_mode();
key_handler.insert(
    KeyEventRegister::n(vec![KeyEvent::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);

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