{"id":15387267,"url":"https://github.com/rhysd/tui-textarea","last_synced_at":"2025-05-14T14:08:18.233Z","repository":{"id":37362870,"uuid":"501217160","full_name":"rhysd/tui-textarea","owner":"rhysd","description":"Simple yet powerful multi-line text editor widget for ratatui and tui-rs","archived":false,"fork":false,"pushed_at":"2024-12-01T09:17:14.000Z","size":388,"stargazers_count":390,"open_issues_count":34,"forks_count":75,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-12T22:45:55.436Z","etag":null,"topics":["editor","ratatui","rust","terminal","tui"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/tui-textarea","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhysd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-08T11:14:39.000Z","updated_at":"2025-05-07T11:28:54.000Z","dependencies_parsed_at":"2023-02-15T22:16:02.295Z","dependency_job_id":"1d0e6b23-619d-45b0-affd-94b8504c23a2","html_url":"https://github.com/rhysd/tui-textarea","commit_stats":{"total_commits":354,"total_committers":11,"mean_commits":32.18181818181818,"dds":0.08192090395480223,"last_synced_commit":"2cae64bae6790cf2b444d51afa2d09ea2ffbbe33"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Ftui-textarea","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Ftui-textarea/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Ftui-textarea/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Ftui-textarea/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhysd","download_url":"https://codeload.github.com/rhysd/tui-textarea/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254159700,"owners_count":22024564,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["editor","ratatui","rust","terminal","tui"],"created_at":"2024-10-01T14:53:08.058Z","updated_at":"2025-05-14T14:08:18.212Z","avatar_url":"https://github.com/rhysd.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"tui-textarea\n============\n[![crate][crates-io-badge]][crate]\n[![docs][doc-badge]][doc]\n[![CI][ci-badge]][ci]\n[![coverage][codecov-badge]][codecov]\n\n[tui-textarea][crate] is a simple yet powerful text editor widget like `\u003ctextarea\u003e` in HTML for [ratatui][] and [tui-rs][].\nMulti-line text editor can be easily put as part of your TUI application.\n\n**Features:**\n\n- Multi-line text editor widget with basic operations (insert/delete characters, auto scrolling, ...)\n- Emacs-like shortcuts (`C-n`/`C-p`/`C-f`/`C-b`, `M-f`/`M-b`, `C-a`/`C-e`, `C-h`/`C-d`, `C-k`, `M-\u003c`/`M-\u003e`, ...)\n- Undo/Redo\n- Line number\n- Cursor line highlight\n- Search with regular expressions\n- Text selection\n- Mouse scrolling\n- Yank support. Paste text deleted with `C-k`, `C-j`, ...\n- Backend agnostic. [crossterm][], [termion][], [termwiz][], and your own backend are all supported\n- Multiple textarea widgets in the same screen\n- Support both [ratatui][] (the fork by community) and [tui-rs][] (the original)\n\n[Documentation][doc]\n\n## Examples\n\nRunning `cargo run --example` in this repository can demonstrate usage of tui-textarea.\n\n### [`minimal`](./examples/minimal.rs)\n\n```sh\ncargo run --example minimal\n```\n\nMinimal usage with [crossterm][] support.\n\n\u003cimg src=\"https://raw.githubusercontent.com/rhysd/ss/master/tui-textarea/minimal.gif\" width=539 height=172 alt=\"minimal example\"\u003e\n\n### [`editor`](./examples/editor.rs)\n\n```sh\ncargo run --example editor --features search file.txt\n```\n\nSimple text editor to edit multiple files.\n\n\u003cimg src=\"https://raw.githubusercontent.com/rhysd/ss/master/tui-textarea/editor.gif\" width=560 height=236 alt=\"editor example\"\u003e\n\n### [`single_line`](./examples/single_line.rs)\n\n```sh\ncargo run --example single_line\n```\n\nSingle-line input form with float number validation.\n\n\u003cimg src=\"https://raw.githubusercontent.com/rhysd/ss/master/tui-textarea/single_line.gif\" width=539 height=92 alt=\"single line example\"\u003e\n\n### [`split`](./examples/split.rs)\n\n```sh\ncargo run --example split\n```\n\nTwo split textareas in a screen and switch them. An example for multiple textarea instances.\n\n\u003cimg src=\"https://raw.githubusercontent.com/rhysd/ss/master/tui-textarea/split.gif\" width=539 height=124 alt=\"multiple textareas example\"\u003e\n\n### [`variable`](./examples/variable.rs)\n\n```sh\ncargo run --example variable\n```\n\nSimple textarea with variable height following the number of lines.\n\n### [`vim`](./examples/vim.rs)\n\n```sh\ncargo run --example vim\n```\n\nVim-like modal text editor. Vim emulation is implemented as a state machine.\n\n\u003cimg src=\"https://raw.githubusercontent.com/rhysd/ss/master/tui-textarea/vim.gif\" width=590 height=156 alt=\"Vim emulation example\"\u003e\n\n### [`popup_placeholder`](./examples/popup_placeholder.rs)\n\n```sh\ncargo run --example popup_placeholder\n```\n\nPopup textarea with a placeholder text.\n\n\u003cimg src=\"https://raw.githubusercontent.com/rhysd/ss/master/tui-textarea/placepop.gif\" width=446 height=220 alt=\"popup textarea with placeholder example\"\u003e\n\n### [`password`](./examples/password.rs)\n\n```sh\ncargo run --example password\n```\n\nPassword input form with masking text with ●.\n\n\u003cimg src=\"https://raw.githubusercontent.com/rhysd/ss/master/tui-textarea/password.gif\" width=589 height=92 alt=\"password example\"\u003e\n\n### [`termion`](./examples/termion.rs)\n\n```sh\ncargo run --example termion --no-default-features --features=termion\n```\n\nMinimal usage with [termion][] support.\n\n### [`termwiz`](./examples/termwiz.rs)\n\n```sh\ncargo run --example termwiz --no-default-features --features=termwiz\n```\n\nMinimal usage with [termwiz][] support.\n\n### Examples for [tui-rs][] support\n\nAll above examples use [ratatui][], but some examples provide tui-rs version. Try `tuirs_` prefix. In these cases, you\nneed to specify features to use tui-rs and `--no-default-features` flag explicitly.\n\n```sh\n# tui-rs version of `minimal` example\ncargo run --example tuirs_minimal --no-default-features --features=tuirs-crossterm\n\n# tui-rs version of `editor` example\ncargo run --example tuirs_editor --no-default-features --features=tuirs-crossterm,search file.txt\n\n# tui-rs version of `termion` example\ncargo run --example tuirs_termion --no-default-features --features=tuirs-termion\n```\n\n## Installation\n\nAdd `tui-textarea` crate to dependencies in your `Cargo.toml`. This enables crossterm backend support by default.\n\n```toml\n[dependencies]\nratatui = \"*\"\ntui-textarea = \"*\"\n```\n\nIf you need text search with regular expressions, enable `search` feature. It adds [regex crate][regex] as dependency.\n\n```toml\n[dependencies]\nratatui = \"*\"\ntui-textarea = { version = \"*\", features = [\"search\"] }\n```\n\nIf you're using ratatui with [termion][] or [termwiz][], enable the `termion` or `termwiz` feature instead of\n`crossterm` feature.\n\n```toml\n[dependencies]\n\n# For termion\nratatui = { version = \"*\", default-features = false, features = [\"termion\"] }\ntui-textarea = { version = \"*\", default-features = false, features = [\"termion\"] }\n\n# For termwiz\nratatui = { version = \"*\", default-features = false, features = [\"termwiz\"] }\ntui-textarea = { version = \"*\", default-features = false, features = [\"termwiz\"] }\n```\n\nIf you're using [tui-rs][] instead of [ratatui][], you need to enable features for using tui-rs crate and to disable\ndefault features. The following table shows feature names corresponding to the dependencies.\n\n|         | crossterm                        | termion         | termwiz   | Your own backend   |\n|---------|----------------------------------|-----------------|-----------|--------------------|\n| ratatui | `crossterm` (enabled by default) | `termion`       | `termwiz` | `no-backend`       |\n| tui-rs  | `tuirs-crossterm`                | `tuirs-termion` | N/A       | `tuirs-no-backend` |\n\nFor example, when you want to use the combination of [tui-rs][] and [crossterm][],\n\n```toml\n[dependencies]\ntui = \"*\"\ntui-textarea = { version = \"*\", features = [\"tuirs-crossterm\"], default-features = false }\n```\n\nNote that [ratatui][] support and [tui-rs][] support are exclusive. When you use [tui-rs][] support, you must disable\n[ratatui][] support by `default-features = false`.\n\nIn addition to above dependencies, you also need to install [crossterm][] or [termion][] or [termwiz][] to initialize\nyour application and to receive key inputs. Note that the dependency versions of [crossterm][] crate and [termion][]\ncrate differ between [ratatui][] and [tui-rs][]. Please make sure to use the same version that matches the package you\nare using. For example, [tui-rs][] depends on [crossterm][] v0.2.5 or [termion][] v1.5 where both crates are older than\n[ratatui][]'s dependencies.\n\n## Minimal Usage\n\n```rust,ignore\nuse tui_textarea::TextArea;\nuse crossterm::event::{Event, read};\n\nlet mut term = ratatui::Terminal::new(...);\n\n// Create an empty `TextArea` instance which manages the editor state\nlet mut textarea = TextArea::default();\n\n// Event loop\nloop {\n    term.draw(|f| {\n        // Get `ratatui::layout::Rect` where the editor should be rendered\n        let rect = ...;\n        // Render the textarea in terminal screen\n        f.render_widget(\u0026textarea, rect);\n    })?;\n\n    if let Event::Key(key) = read()? {\n        // Your own key mapping to break the event loop\n        if key.code == KeyCode::Esc {\n            break;\n        }\n        // `TextArea::input` can directly handle key events from backends and update the editor state\n        textarea.input(key);\n    }\n}\n\n// Get text lines as `\u0026[String]`\nprintln!(\"Lines: {:?}\", textarea.lines());\n```\n\n`TextArea` is an instance to manage the editor state. By default, it disables line numbers and highlights cursor line\nwith underline.\n\n`\u0026TextArea` reference implements ratatui's `Widget` trait. Render it on every tick of event loop.\n\n`TextArea::input()` receives inputs from tui backends. The method can take key events from backends such as\n`crossterm::event::KeyEvent` or `termion::event::Key` directly if the features are enabled. The method handles default\nkey mappings as well.\n\nDefault key mappings are as follows:\n\n| Mappings                                     | Description                               |\n|----------------------------------------------|-------------------------------------------|\n| `Ctrl+H`, `Backspace`                        | Delete one character before cursor        |\n| `Ctrl+D`, `Delete`                           | Delete one character next to cursor       |\n| `Ctrl+M`, `Enter`                            | Insert newline                            |\n| `Ctrl+K`                                     | Delete from cursor until the end of line  |\n| `Ctrl+J`                                     | Delete from cursor until the head of line |\n| `Ctrl+W`, `Alt+H`, `Alt+Backspace`           | Delete one word before cursor             |\n| `Alt+D`, `Alt+Delete`                        | Delete one word next to cursor            |\n| `Ctrl+U`                                     | Undo                                      |\n| `Ctrl+R`                                     | Redo                                      |\n| `Ctrl+C`, `Copy`                             | Copy selected text                        |\n| `Ctrl+X`, `Cut`                              | Cut selected text                         |\n| `Ctrl+Y`, `Paste`                            | Paste yanked text                         |\n| `Ctrl+F`, `→`                                | Move cursor forward by one character      |\n| `Ctrl+B`, `←`                                | Move cursor backward by one character     |\n| `Ctrl+P`, `↑`                                | Move cursor up by one line                |\n| `Ctrl+N`, `↓`                                | Move cursor down by one line              |\n| `Alt+F`, `Ctrl+→`                            | Move cursor forward by word               |\n| `Atl+B`, `Ctrl+←`                            | Move cursor backward by word              |\n| `Alt+]`, `Alt+P`, `Ctrl+↑`                   | Move cursor up by paragraph               |\n| `Alt+[`, `Alt+N`, `Ctrl+↓`                   | Move cursor down by paragraph             |\n| `Ctrl+E`, `End`, `Ctrl+Alt+F`, `Ctrl+Alt+→`  | Move cursor to the end of line            |\n| `Ctrl+A`, `Home`, `Ctrl+Alt+B`, `Ctrl+Alt+←` | Move cursor to the head of line           |\n| `Alt+\u003c`, `Ctrl+Alt+P`, `Ctrl+Alt+↑`          | Move cursor to top of lines               |\n| `Alt+\u003e`, `Ctrl+Alt+N`, `Ctrl+Alt+↓`          | Move cursor to bottom of lines            |\n| `Ctrl+V`, `PageDown`                         | Scroll down by page                       |\n| `Alt+V`, `PageUp`                            | Scroll up by page                         |\n\nDeleting multiple characters at once saves the deleted text to yank buffer. It can be pasted with `Ctrl+Y` later.\n\nIf you don't want to use default key mappings, see the 'Advanced Usage' section.\n\n## Basic Usage\n\n### Create `TextArea` instance with text\n\n`TextArea` implements `Default` trait to create an editor instance with an empty text.\n\n```rust,ignore\nlet mut textarea = TextArea::default();\n```\n\n`TextArea::new()` creates an editor instance with text lines passed as `Vec\u003cString\u003e`.\n\n```rust,ignore\nlet mut lines: Vec\u003cString\u003e = ...;\nlet mut textarea = TextArea::new(lines);\n```\n\n`TextArea` implements `From\u003cimpl Iterator\u003cItem=impl Into\u003cString\u003e\u003e\u003e`. `TextArea::from()` can create an editor instance\nfrom any iterators whose elements can be converted to `String`.\n\n```rust,ignore\n// Create `TextArea` from from `[\u0026str]`\nlet mut textarea = TextArea::from([\n    \"this is first line\",\n    \"this is second line\",\n    \"this is third line\",\n]);\n\n// Create `TextArea` from `String`\nlet mut text: String = ...;\nlet mut textarea = TextArea::from(text.lines());\n```\n\n`TextArea` also implements `FromIterator\u003cimpl Into\u003cString\u003e\u003e`. `Iterator::collect()` can collect strings as an editor\ninstance. This allows to create `TextArea` reading lines from file efficiently using `io::BufReader`.\n\n```rust,ignore\nlet file = fs::File::open(path)?;\nlet mut textarea: TextArea = io::BufReader::new(file).lines().collect::\u003cio::Result\u003c_\u003e\u003e()?;\n```\n\n### Get text contents from `TextArea`\n\n`TextArea::lines()` returns text lines as `\u0026[String]`. It borrows text contents temporarily.\n\n```rust,ignore\nlet text: String = textarea.lines().join(\"\\n\");\n```\n\n`TextArea::into_lines()` moves `TextArea` instance into text lines as `Vec\u003cString\u003e`. This can retrieve the text contents\nwithout any copy.\n\n```rust,ignore\nlet lines: Vec\u003cString\u003e = textarea.into_lines();\n```\n\nNote that `TextArea` always contains at least one line. For example, an empty text means one empty line. This is because\nany text file must end with newline.\n\n```rust,ignore\nlet textarea = TextArea::default();\nassert_eq!(textarea.into_lines(), [\"\"]);\n```\n\n### Show line number\n\nBy default, `TextArea` does now show line numbers. To enable, set a style for rendering line numbers by\n`TextArea::set_line_number_style()`. For example, the following renders line numbers in dark gray background\ncolor.\n\n```rust,ignore\nuse ratatui::style::{Style, Color};\n\nlet style = Style::default().bg(Color::DarkGray);\ntextarea.set_line_number_style(style);\n```\n\n### Configure cursor line style\n\nBy default, `TextArea` renders the line at cursor with underline so that users can easily notice where the current line\nis. To change the style of cursor line, use `TextArea::set_cursor_line_style()`. For example, the following styles the\ncursor line with bold text.\n\n```rust,ignore\nuse ratatui::style::{Style, Modifier};\n\nlet style = Style::default().add_modifier(Modifier::BOLD);\ntextarea.set_cursor_line_style(style);\n```\n\nTo disable cursor line style, set the default style as follows:\n\n```rust,ignore\nuse ratatui::style::{Style, Modifier};\n\ntextarea.set_cursor_line_style(Style::default());\n```\n\n### Configure tab width\n\nThe default tab width is 4. To change it, use `TextArea::set_tab_length()` method. The following sets 2 to tab width.\nTyping tab key inserts 2 spaces.\n\n```rust,ignore\ntextarea.set_tab_length(2);\n```\n\n### Configure max history size\n\nBy default, past 50 modifications are stored as edit history. The history is used for undo/redo. To change how many past\nedits are remembered, use `TextArea::set_max_histories()` method. The following remembers past 1000 changes.\n\n```rust,ignore\ntextarea.set_max_histories(1000);\n```\n\nSetting 0 disables undo/redo.\n\n```rust,ignore\ntextarea.set_max_histories(0);\n```\n\n### Text search with regular expressions\n\nTo search text in textarea, set a regular expression pattern with `TextArea::set_search_pattern()` and move cursor with\n`TextArea::search_forward()` for forward search or `TextArea::search_back()` backward search. The regular expression is\nhandled by [`regex` crate][regex].\n\nText search wraps around the textarea. When searching forward and no match found until the end of textarea, it searches\nthe pattern from start of the file.\n\nMatches are highlighted in textarea. The text style to highlight matches can be changed with\n`TextArea::set_search_style()`. Setting an empty string to `TextArea::set_search_pattern()` stops the text search.\n\n```rust,ignore\n// Start text search matching to \"hello\" or \"hi\". This highlights matches in textarea but does not move cursor.\n// `regex::Error` is returned on invalid pattern.\ntextarea.set_search_pattern(\"(hello|hi)\").unwrap();\n\ntextarea.search_forward(false); // Move cursor to the next match\ntextarea.search_back(false);    // Move cursor to the previous match\n\n// Setting empty string stops the search\ntextarea.set_search_pattern(\"\").unwrap();\n```\n\nNo UI is provided for text search. You need to provide your own UI to input search query. It is recommended to use\nanother `TextArea` for search form. To build a single-line input form, see 'Single-line input like `\u003cinput\u003e` in HTML' in\n'Advanced Usage' section below.\n\n[`editor` example](./examples/editor.rs) implements a text search with search form built on `TextArea`. See the\nimplementation for working example.\n\nTo use text search, `search` feature needs to be enabled in your `Cargo.toml`. It is disabled by default to avoid\ndepending on `regex` crate until it is necessary.\n\n```toml\ntui-textarea = { version = \"*\", features = [\"search\"] }\n```\n\n## Advanced Usage\n\n### Single-line input like `\u003cinput\u003e` in HTML\n\nTo use `TextArea` for a single-line input widget like `\u003cinput\u003e` in HTML, ignore all key mappings which inserts newline.\n\n```rust,ignore\nuse crossterm::event::{Event, read};\nuse tui_textarea::{Input, Key};\n\nlet default_text: \u0026str = ...;\nlet default_text = default_text.replace(\u0026['\\n', '\\r'], \" \"); // Ensure no new line is contained\nlet mut textarea = TextArea::new(vec![default_text]);\n\n// Event loop\nloop {\n    // ...\n\n    // Using `Input` is not mandatory, but it's useful for pattern match\n    // Ignore Ctrl+m and Enter. Otherwise handle keys as usual\n    match read()?.into() {\n        Input { key: Key::Char('m'), ctrl: true, alt: false }\n        | Input { key: Key::Enter, .. } =\u003e continue,\n        input =\u003e {\n            textarea.input(key);\n        }\n    }\n}\n\nlet text = textarea.into_lines().remove(0); // Get input text\n```\n\nSee [`single_line` example](./examples/single_line.rs) for working example.\n\n### Define your own key mappings\n\nAll editor operations are defined as public methods of `TextArea`. To move cursor, use `tui_textarea::CursorMove` to\nnotify how to move the cursor.\n\n| Method                                               | Operation                                       |\n|------------------------------------------------------|-------------------------------------------------|\n| `textarea.delete_char()`                             | Delete one character before cursor              |\n| `textarea.delete_next_char()`                        | Delete one character next to cursor             |\n| `textarea.insert_newline()`                          | Insert newline                                  |\n| `textarea.delete_line_by_end()`                      | Delete from cursor until the end of line        |\n| `textarea.delete_line_by_head()`                     | Delete from cursor until the head of line       |\n| `textarea.delete_word()`                             | Delete one word before cursor                   |\n| `textarea.delete_next_word()`                        | Delete one word next to cursor                  |\n| `textarea.undo()`                                    | Undo                                            |\n| `textarea.redo()`                                    | Redo                                            |\n| `textarea.copy()`                                    | Copy selected text                              |\n| `textarea.cut()`                                     | Cut selected text                               |\n| `textarea.paste()`                                   | Paste yanked text                               |\n| `textarea.start_selection()`                         | Start text selection                            |\n| `textarea.cancel_selection()`                        | Cancel text selection                           |\n| `textarea.select_all()`                              | Select entire text                              |\n| `textarea.move_cursor(CursorMove::Forward)`          | Move cursor forward by one character            |\n| `textarea.move_cursor(CursorMove::Back)`             | Move cursor backward by one character           |\n| `textarea.move_cursor(CursorMove::Up)`               | Move cursor up by one line                      |\n| `textarea.move_cursor(CursorMove::Down)`             | Move cursor down by one line                    |\n| `textarea.move_cursor(CursorMove::WordForward)`      | Move cursor forward by word                     |\n| `textarea.move_cursor(CursorMove::WordEnd)`          | Move cursor to next end of word                 |\n| `textarea.move_cursor(CursorMove::WordBack)`         | Move cursor backward by word                    |\n| `textarea.move_cursor(CursorMove::ParagraphForward)` | Move cursor up by paragraph                     |\n| `textarea.move_cursor(CursorMove::ParagraphBack)`    | Move cursor down by paragraph                   |\n| `textarea.move_cursor(CursorMove::End)`              | Move cursor to the end of line                  |\n| `textarea.move_cursor(CursorMove::Head)`             | Move cursor to the head of line                 |\n| `textarea.move_cursor(CursorMove::Top)`              | Move cursor to top of lines                     |\n| `textarea.move_cursor(CursorMove::Bottom)`           | Move cursor to bottom of lines                  |\n| `textarea.move_cursor(CursorMove::Jump(row, col))`   | Move cursor to (row, col) position              |\n| `textarea.move_cursor(CursorMove::InViewport)`       | Move cursor to stay in the viewport             |\n| `textarea.set_search_pattern(pattern)`               | Set a pattern for text search                   |\n| `textarea.search_forward(match_cursor)`              | Move cursor to next match of text search        |\n| `textarea.search_back(match_cursor)`                 | Move cursor to previous match of text search    |\n| `textarea.scroll(Scrolling::PageDown)`               | Scroll down the viewport by page                |\n| `textarea.scroll(Scrolling::PageUp)`                 | Scroll up the viewport by page                  |\n| `textarea.scroll(Scrolling::HalfPageDown)`           | Scroll down the viewport by half-page           |\n| `textarea.scroll(Scrolling::HalfPageUp)`             | Scroll up the viewport by half-page             |\n| `textarea.scroll((row, col))`                        | Scroll down the viewport to (row, col) position |\n\nTo define your own key mappings, simply call the above methods in your code instead of `TextArea::input()` method.\n\nSee the [`vim` example](./examples/vim.rs) for working example. It implements more Vim-like key modal mappings.\n\nIf you don't want to use default key mappings, `TextArea::input_without_shortcuts()` method can be used instead of\n`TextArea::input()`. The method only handles very basic operations such as inserting/deleting single characters, tabs,\nnewlines.\n\n```rust,ignore\nmatch read()?.into() {\n    // Handle your own key mappings here\n    // ...\n    input =\u003e textarea.input_without_shortcuts(input),\n}\n```\n\n### Use your own backend\n\nratatui and tui-rs allows to make your own backend by implementing [`ratatui::backend::Backend`][ratatui-backend] trait.\ntui-textarea supports it as well. Please use `no-backend` feature for [ratatui][] or `tuirs-no-backend` feature for\n[tui-rs][]. They avoid adding backend crates (crossterm, termion, or termwiz) since you're using your own backend.\n\n```toml\n[dependencies]\n# For ratatui\ntui-textarea = { version = \"*\", default-features = false, features = [\"no-backend\"] }\n# For tui-rs\ntui-textarea = { version = \"*\", default-features = false, features = [\"tuirs-no-backend\"] }\n```\n\n`tui_textarea::Input` is a type for backend-agnostic key input. What you need to do is converting key event in your own\nbackend into the `tui_textarea::Input` instance. Then `TextArea::input()` method can handle the input as other backend.\n\nIn the following example, let's say `your_backend::KeyDown` is a key event type for your backend and\n`your_backend::read_next_key()` returns the next key event.\n\n```rust,ignore\n// In your backend implementation\n\npub enum KeyDown {\n    Char(char),\n    BS,\n    Del,\n    Esc,\n    // ...\n}\n\n// Return tuple of (key, ctrlkey, altkey)\npub fn read_next_key() -\u003e (KeyDown, bool, bool) {\n    // ...\n}\n```\n\nThen you can implement the logic to convert `your_backend::KeyDown` value into `tui_textarea::Input` value.\n\n```rust,ignore\nuse tui_textarea::{Input, Key};\nuse your_backend::KeyDown;\n\nfn keydown_to_input(key: KeyDown, ctrl: bool, alt: bool) -\u003e Input {\n    match key {\n        KeyDown::Char(c) =\u003e Input { key: Key::Char(c), ctrl, alt },\n        KeyDown::BS =\u003e Input { key: Key::Backspace, ctrl, alt },\n        KeyDown::Del =\u003e Input { key: Key::Delete, ctrl, alt },\n        KeyDown::Esc =\u003e Input { key: Key::Esc, ctrl, alt },\n        // ...\n        _ =\u003e Input::default(),\n    }\n}\n```\n\nFor the keys which are not handled by tui-textarea, `tui_textarea::Input::default()` is available. It returns 'null'\nkey. An editor will do nothing with the key.\n\nFinally, convert your own backend's key input type into `tui_textarea::Input` and pass it to `TextArea::input()`.\n\n```rust,ignore\nlet mut textarea = ...;\n\n// Event loop\nloop {\n    // ...\n\n    let (key, ctrl, alt) = your_backend::read_next_key();\n    if key == your_backend::KeyDown::Esc {\n        break; // For example, quit your app on pressing Esc\n    }\n    textarea.input(keydown_to_input(key, ctrl, alt));\n}\n```\n\n### Put multiple `TextArea` instances in screen\n\nYou don't need to do anything special. Create multiple `TextArea` instances and render widgets built from each instances.\n\nThe following is an example to put two textarea widgets in application and manage the focus.\n\n```rust,ignore\nuse tui_textarea::{TextArea, Input, Key};\nuse crossterm::event::{Event, read};\n\nlet editors = \u0026mut [\n    TextArea::default(),\n    TextArea::default(),\n];\n\nlet mut focused = 0;\n\nloop {\n    term.draw(|f| {\n        let rects = ...;\n\n        for (editor, rect) in editors.iter().zip(rects.into_iter()) {\n            f.render_widget(editor, rect);\n        }\n    })?;\n\n    match read()?.into() {\n        // Switch focused textarea by Ctrl+S\n        Input { key: Key::Char('s'), ctrl: true, .. } =\u003e focused = (focused + 1) % 2;\n        // Handle input by the focused editor\n        input =\u003e editors[focused].input(input),\n    }\n}\n```\n\nSee [`split` example](./examples/split.rs) and [`editor` example](./examples/editor.rs) for working example.\n\n### Serialization/Deserialization support\n\nThis crate optionally supports [serde][] crate by enabling `serde` feature.\n\n```toml\n[dependencies]\ntui-textarea = { version = \"*\", features = [\"serde\"] }\n```\n\nValues of the following types can be serialized/deserialized:\n\n- `Key`\n- `Input`\n- `CursorMove`\n- `Scrolling`\n\nHere is an example for deserializing key input from JSON using [serde_json][].\n\n```rust,ignore\nuse tui_textarea::Input;\n\nlet json = r#\"\n    {\n        \"key\": { \"Char\": \"a\" },\n        \"ctrl\": true,\n        \"alt\": false,\n        \"shift\": true\n    }\n\"#;\n\nlet input: Input = serde_json::from_str(json).unwrap();\nprintln!(\"{input:?}\");\n// Input {\n//     key: Key::Char('a'),\n//     ctrl: true,\n//     alt: false,\n//     shift: true,\n// }\n```\n\n## Minimum Supported Rust Version\n\nMSRV of this crate is depending on `tui` crate. Currently MSRV is 1.56.1. Note that `ratatui` crate requires more recent Rust version.\n\n## Versioning\n\nThis crate is not reaching v1.0.0 yet. There is no plan to bump the major version for now. Current versioning policy is\nas follows:\n\n- Major: Fixed to 0\n- Minor: Bump on breaking change\n- Patch: Bump on new feature or bug fix\n\n## Contributing to tui-textarea\n\nThis project is developed [on GitHub][repo].\n\nFor feature requests or bug reports, please [create an issue][new-issue]. For submitting patches, please [create a pull\nrequest][pulls].\n\nPlease read [CONTRIBUTING.md](./CONTRIBUTING.md) before reporting an issue or making a PR.\n\n## License\n\ntui-textarea is distributed under [The MIT License](./LICENSE.txt).\n\n[crates-io-badge]: https://img.shields.io/crates/v/tui-textarea.svg\n[crate]: https://crates.io/crates/tui-textarea\n[doc-badge]: https://docs.rs/tui-textarea/badge.svg\n[doc]: https://docs.rs/tui-textarea/latest/tui_textarea/\n[ci-badge]: https://github.com/rhysd/tui-textarea/actions/workflows/ci.yml/badge.svg?event=push\n[ci]: https://github.com/rhysd/tui-textarea/actions/workflows/ci.yml\n[codecov-badge]: https://codecov.io/gh/rhysd/tui-textarea/graph/badge.svg?token=YAA3EVRXAY\n[codecov]: https://codecov.io/gh/rhysd/tui-textarea\n[tui-rs]: https://github.com/fdehau/tui-rs\n[ratatui]: https://github.com/ratatui/ratatui\n[crossterm]: https://docs.rs/crossterm/latest/crossterm/\n[termion]: https://docs.rs/termion/latest/termion/\n[termwiz]: https://docs.rs/termwiz/latest/termwiz/\n[ratatui-backend]: https://docs.rs/ratatui/latest/ratatui/backend/trait.Backend.html\n[repo]: https://github.com/rhysd/tui-textarea\n[new-issue]: https://github.com/rhysd/tui-textarea/issues/new\n[pulls]: https://github.com/rhysd/tui-textarea/pulls\n[regex]: https://docs.rs/regex/latest/regex/\n[serde]: https://crates.io/crates/serde\n[serde_json]: https://crates.io/crates/serde_json\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhysd%2Ftui-textarea","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhysd%2Ftui-textarea","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhysd%2Ftui-textarea/lists"}