Struct CustomTextArea 

pub struct CustomTextArea<'a> { /* private fields */ }

A custom text area widget

Implementations

impl<'a> CustomTextArea<'a>

pub fn new( style: impl Into<Style>, inline: bool, multiline: bool, text: impl Into<String>, ) -> Self

Creates a new custom text area

pub fn title(self, title: impl Into<Cow<'a, str>>) -> Self

Updates the title of the text area

pub fn forbidden_chars_regex(self, regex: Regex) -> Self

Updates the regex to filter out forbidden characters

pub fn focused(self) -> Self

Updates the text area to be focused

pub fn secret(self, secret: bool) -> Self

Updates the textarea mask char

pub fn is_multiline(&self) -> bool

Returns whether the text area supports multiple lines or not

pub fn is_focused(&self) -> bool

Returns whether the text area is currently focused or not

pub fn set_secret(&mut self, secret: bool)

Sets or clear the the text area mask char

pub fn set_focus(&mut self, focus: bool)

Sets the focus state of the text area

pub fn set_title(&mut self, new_title: impl Into<Cow<'a, str>>)

Updates the title of the text area

pub fn set_forbidden_chars_regex(&mut self, regex: Regex)

Updates the regex to filter out forbidden characters

pub fn set_style(&mut self, style: impl Into<Style>)

Updates the style of this text area

pub fn set_ai_loading(&mut self, loading: bool)

Sets the AI loading state, showing or hiding a spinner

pub fn is_ai_loading(&self) -> bool

Checks if the textarea has the ai loading state

pub fn tick(&mut self)

Advances the spinner animation if active

pub fn lines_as_string(&self) -> String

Retrieves the current text in the text area as a single string

pub fn move_cursor_left(&mut self, word: bool)

Moves the cursor to the left, optionally by word

pub fn move_cursor_right(&mut self, word: bool)

Moves the cursor to the right, optionally by word

pub fn move_home(&mut self, absolute: bool)

Moves the cursor to the head of the line, or the absolute head

pub fn move_end(&mut self, absolute: bool)

Moves the cursor to the end of the line, or the absolute end

pub fn insert_char(&mut self, c: char)

Inserts a char at the current cursor position

pub fn insert_str<S>(&mut self, text: S)

where S: AsRef<str>,

Inserts a text at the current cursor position

pub fn insert_newline(&mut self)

Inserts a newline at the current cursor position, if multiline is enabled

pub fn delete(&mut self, backspace: bool, word: bool)

Delete characters at the cursor position based on the backspace and word flags

Methods from Deref<Target = TextArea<'a>>

pub fn input(&mut self, input: impl Into<Input>) -> bool

Handle a key input with default key mappings. For default key mappings, see the table in the module document. crossterm, termion, and termwiz features enable conversion from their own key event types into Input so this method can take the event values directly. This method returns if the input modified text contents or not in the textarea.

use ratatui_textarea::{TextArea, Key, Input};

let mut textarea = TextArea::default();

// Handle crossterm key events
let event: crossterm::event::Event = ...;
textarea.input(event);
if let crossterm::event::Event::Key(key) = event {
    textarea.input(key);
}

// Handle termion key events
let event: termion::event::Event = ...;
textarea.input(event);
if let termion::event::Event::Key(key) = event {
    textarea.input(key);
}

// Handle termwiz key events
let event: termwiz::input::InputEvent = ...;
textarea.input(event);
if let termwiz::input::InputEvent::Key(key) = event {
    textarea.input(key);
}

// Handle backend-agnostic key input
let input = Input { key: Key::Char('a'), ctrl: false, alt: false, shift: false };
let modified = textarea.input(input);
assert!(modified);

pub fn input_without_shortcuts(&mut self, input: impl Into<Input>) -> bool

Handle a key input without default key mappings. This method handles only

• Single character input without modifier keys
• Tab
• Enter
• Backspace
• Delete

This method returns if the input modified text contents or not in the textarea.

This method is useful when you want to define your own key mappings and don’t want default key mappings. See ‘Define your own key mappings’ section in the module document.

pub fn insert_char(&mut self, c: char)

Insert a single character at current cursor position.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

textarea.insert_char('a');
assert_eq!(textarea.lines(), ["a"]);

pub fn insert_str<S>(&mut self, s: S) -> bool

where S: AsRef<str>,

Insert a string at current cursor position. This method returns if some text was inserted or not in the textarea. Both \n and \r\n are recognized as newlines but \r isn’t.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

textarea.insert_str("hello");
assert_eq!(textarea.lines(), ["hello"]);

textarea.insert_str(", world\ngoodbye, world");
assert_eq!(textarea.lines(), ["hello, world", "goodbye, world"]);

pub fn delete_str(&mut self, chars: usize) -> bool

Delete a string from the current cursor position. The chars parameter means number of characters, not a byte length of the string. Newlines at the end of lines are counted in the number. This method returns if some text was deleted or not.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["🐱🐶🐰🐮"]);
textarea.move_cursor(CursorMove::Forward);

textarea.delete_str(2);
assert_eq!(textarea.lines(), ["🐱🐮"]);

let mut textarea = TextArea::from(["🐱", "🐶", "🐰", "🐮"]);
textarea.move_cursor(CursorMove::Down);

textarea.delete_str(4); // Deletes 🐶, \n, 🐰, \n
assert_eq!(textarea.lines(), ["🐱", "🐮"]);

pub fn insert_tab(&mut self) -> bool

Insert a tab at current cursor position. Note that this method does nothing when the tab length is 0. This method returns if a tab string was inserted or not in the textarea.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["hi"]);

textarea.move_cursor(CursorMove::End); // Move to the end of line

textarea.insert_tab();
assert_eq!(textarea.lines(), ["hi  "]);
textarea.insert_tab();
assert_eq!(textarea.lines(), ["hi      "]);

pub fn insert_newline(&mut self)

Insert a newline at current cursor position.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["hi"]);

textarea.move_cursor(CursorMove::Forward);
textarea.insert_newline();
assert_eq!(textarea.lines(), ["h", "i"]);

pub fn delete_newline(&mut self) -> bool

Delete a newline from head of current cursor line. This method returns if a newline was deleted or not in the textarea. When some text is selected, it is deleted instead.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["hello", "world"]);

textarea.move_cursor(CursorMove::Down);
textarea.delete_newline();
assert_eq!(textarea.lines(), ["helloworld"]);

pub fn delete_char(&mut self) -> bool

Delete one character before cursor. When the cursor is at head of line, the newline before the cursor will be removed. This method returns if some text was deleted or not in the textarea. When some text is selected, it is deleted instead.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["abc"]);

textarea.move_cursor(CursorMove::Forward);
textarea.delete_char();
assert_eq!(textarea.lines(), ["bc"]);

pub fn delete_next_char(&mut self) -> bool

Delete one character next to cursor. When the cursor is at end of line, the newline next to the cursor will be removed. This method returns if a character was deleted or not in the textarea.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["abc"]);

textarea.move_cursor(CursorMove::Forward);
textarea.delete_next_char();
assert_eq!(textarea.lines(), ["ac"]);

pub fn delete_line_by_end(&mut self) -> bool

Delete string from cursor to end of the line. When the cursor is at end of line, the newline next to the cursor is removed. This method returns if some text was deleted or not in the textarea.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["abcde"]);

// Move to 'c'
textarea.move_cursor(CursorMove::Forward);
textarea.move_cursor(CursorMove::Forward);

textarea.delete_line_by_end();
assert_eq!(textarea.lines(), ["ab"]);

pub fn delete_line_by_head(&mut self) -> bool

Delete string from cursor to head of the line. When the cursor is at head of line, the newline before the cursor will be removed. This method returns if some text was deleted or not in the textarea.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["abcde"]);

// Move to 'c'
textarea.move_cursor(CursorMove::Forward);
textarea.move_cursor(CursorMove::Forward);

textarea.delete_line_by_head();
assert_eq!(textarea.lines(), ["cde"]);

pub fn delete_word(&mut self) -> bool

Delete a word before cursor. Word boundary appears at spaces, punctuations, and others. For example fn foo(a) consists of words fn, foo, (, a, ). When the cursor is at head of line, the newline before the cursor will be removed.

This method returns if some text was deleted or not in the textarea.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["aaa bbb ccc"]);

textarea.move_cursor(CursorMove::End);

textarea.delete_word();
assert_eq!(textarea.lines(), ["aaa bbb "]);
textarea.delete_word();
assert_eq!(textarea.lines(), ["aaa "]);

pub fn delete_next_word(&mut self) -> bool

Delete a word next to cursor. Word boundary appears at spaces, punctuations, and others. For example fn foo(a) consists of words fn, foo, (, a, ). When the cursor is at end of line, the newline next to the cursor will be removed.

This method returns if some text was deleted or not in the textarea.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::from(["aaa bbb ccc"]);

textarea.delete_next_word();
assert_eq!(textarea.lines(), [" bbb ccc"]);
textarea.delete_next_word();
assert_eq!(textarea.lines(), [" ccc"]);

pub fn clear(&mut self) -> bool

Clear the entire content of the textarea, leaving it empty. The cursor position before calling this method does not affect the result. This method integrates with the undo/redo history, so the content can be restored with TextArea::undo. Returns true if any text was deleted, false if the textarea was already empty.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::from(["hello", "world"]);

assert!(textarea.clear());
assert!(textarea.is_empty());

textarea.undo();
assert_eq!(textarea.lines(), ["hello", "world"]);

pub fn paste(&mut self) -> bool

Paste a string previously deleted by TextArea::delete_line_by_head, TextArea::delete_line_by_end, TextArea::delete_word, TextArea::delete_next_word. This method returns if some text was inserted or not in the textarea.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["aaa bbb ccc"]);

textarea.delete_next_word();
textarea.move_cursor(CursorMove::End);
textarea.paste();
assert_eq!(textarea.lines(), [" bbb cccaaa"]);

pub fn start_selection(&mut self)

Start text selection at the cursor position. If text selection is already ongoing, the start position is reset.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["aaa bbb ccc"]);

textarea.start_selection();
textarea.move_cursor(CursorMove::WordForward);
textarea.copy();
assert_eq!(textarea.yank_text(), "aaa ");

pub fn cancel_selection(&mut self)

Stop the current text selection. This method does nothing if text selection is not ongoing.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["aaa bbb ccc"]);

textarea.start_selection();
textarea.move_cursor(CursorMove::WordForward);

// Cancel the ongoing text selection
textarea.cancel_selection();

// As the result, this `copy` call does nothing
textarea.copy();
assert_eq!(textarea.yank_text(), "");

pub fn select_all(&mut self)

Select the entire text. Cursor moves to the end of the text buffer. When text selection is already ongoing, it is canceled.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["aaa", "bbb", "ccc"]);

textarea.select_all();

// Cut the entire text;
textarea.cut();

assert_eq!(textarea.lines(), [""]); // Buffer is now empty
assert_eq!(textarea.yank_text(), "aaa\nbbb\nccc");

pub fn is_selecting(&self) -> bool

Return if text selection is ongoing or not.

use ratatui_textarea::{TextArea};

let mut textarea = TextArea::default();

assert!(!textarea.is_selecting());
textarea.start_selection();
assert!(textarea.is_selecting());
textarea.cancel_selection();
assert!(!textarea.is_selecting());

pub fn set_selection_style(&mut self, style: Style)

Set the style used for text selection. The default style is light blue.

use ratatui_textarea::TextArea;
use ratatui_core::style::{Style, Color};

let mut textarea = TextArea::default();

// Change the selection color from the default to Red
textarea.set_selection_style(Style::default().bg(Color::Red));
assert_eq!(textarea.selection_style(), Style::default().bg(Color::Red));

pub fn selection_style(&mut self) -> Style

Get the style used for text selection.

use ratatui_textarea::TextArea;
use ratatui_core::style::{Style, Color};

let mut textarea = TextArea::default();

assert_eq!(textarea.selection_style(), Style::default().bg(Color::LightBlue));

pub fn copy(&mut self)

Copy the selection text to the yank buffer. When nothing is selected, this method does nothing. To get the yanked text, use TextArea::yank_text.

use ratatui_textarea::{TextArea, Key, Input, CursorMove};

let mut textarea = TextArea::from(["Hello World"]);

// Start text selection at 'W'
textarea.move_cursor(CursorMove::WordForward);
textarea.start_selection();

// Select the word "World" and copy the selected text
textarea.move_cursor(CursorMove::End);
textarea.copy();

assert_eq!(textarea.yank_text(), "World");
assert_eq!(textarea.lines(), ["Hello World"]); // Text does not change

pub fn cut(&mut self) -> bool

Cut the selected text and place it in the yank buffer. This method returns whether the text was modified. The cursor will move to the start position of the text selection. To get the yanked text, use TextArea::yank_text.

use ratatui_textarea::{TextArea, Key, Input, CursorMove};

let mut textarea = TextArea::from(["Hello World"]);

// Start text selection at 'W'
textarea.move_cursor(CursorMove::WordForward);
textarea.start_selection();

// Select the word "World" and copy the selected text
textarea.move_cursor(CursorMove::End);
textarea.cut();

assert_eq!(textarea.yank_text(), "World");
assert_eq!(textarea.lines(), ["Hello "]);

pub fn move_cursor(&mut self, m: CursorMove)

Move the cursor to the position specified by the CursorMove parameter. For each kind of cursor moves, see the document of CursorMove.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["abc", "def"]);

textarea.move_cursor(CursorMove::Forward);
assert_eq!(textarea.cursor(), (0, 1));
textarea.move_cursor(CursorMove::Down);
assert_eq!(textarea.cursor(), (1, 1));

pub fn undo(&mut self) -> bool

Undo the last modification. This method returns if the undo modified text contents or not in the textarea.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["abc def"]);

textarea.delete_next_word();
assert_eq!(textarea.lines(), [" def"]);
textarea.undo();
assert_eq!(textarea.lines(), ["abc def"]);

pub fn redo(&mut self) -> bool

Redo the last undo change. This method returns if the redo modified text contents or not in the textarea.

use ratatui_textarea::{TextArea, CursorMove};

let mut textarea = TextArea::from(["abc def"]);

textarea.delete_next_word();
assert_eq!(textarea.lines(), [" def"]);
textarea.undo();
assert_eq!(textarea.lines(), ["abc def"]);
textarea.redo();
assert_eq!(textarea.lines(), [" def"]);

pub fn widget(&'a self) -> impl Widget + 'a

👎Deprecated since 0.5.3:

calling this method is no longer necessary on rendering a textarea. pass &TextArea reference to Frame::render_widget method call directly

Build a ratatui (or tui-rs) widget to render the current state of the textarea. The widget instance returned from this method can be rendered with ratatui_core::terminal::Frame::render_widget.

This method was deprecated at v0.5.3 and is no longer necessary. Instead you can directly pass &TextArea reference to the Frame::render_widget method call.

// v0.5.2 or earlier
f.render_widget(textarea.widget(), rect);

// v0.5.3 or later
f.render_widget(&textarea, rect);

pub fn set_style(&mut self, style: Style)

Set the style of textarea. By default, textarea is not styled.

use ratatui_core::style::{Style, Color};
use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();
let style = Style::default().fg(Color::Red);
textarea.set_style(style);
assert_eq!(textarea.style(), style);

pub fn style(&self) -> Style

Get the current style of textarea.

pub fn set_block(&mut self, block: Block<'a>)

Set the block of textarea. By default, no block is set.

use ratatui_textarea::TextArea;
use ratatui_widgets::block::Block;
use ratatui_widgets::borders::Borders;

let mut textarea = TextArea::default();
let block = Block::default().borders(Borders::ALL).title("Block Title");
textarea.set_block(block);
assert!(textarea.block().is_some());

pub fn remove_block(&mut self)

Remove the block of textarea which was set by TextArea::set_block.

use ratatui_textarea::TextArea;
use ratatui_widgets::block::Block;
use ratatui_widgets::borders::Borders;

let mut textarea = TextArea::default();
let block = Block::default().borders(Borders::ALL).title("Block Title");
textarea.set_block(block);
textarea.remove_block();
assert!(textarea.block().is_none());

pub fn block<'s>(&'s self) -> Option<&'s Block<'a>>

Get the block of textarea if exists.

pub fn set_tab_length(&mut self, len: u8)

Set the length of tab character. Setting 0 disables tab inputs.

use ratatui_textarea::{TextArea, Input, Key};

let mut textarea = TextArea::default();
let tab_input = Input { key: Key::Tab, ctrl: false, alt: false, shift: false };

textarea.set_tab_length(8);
textarea.input(tab_input.clone());
assert_eq!(textarea.lines(), ["        "]);

textarea.set_tab_length(2);
textarea.input(tab_input);
assert_eq!(textarea.lines(), ["          "]);

pub fn tab_length(&self) -> u8

Get how many spaces are used for representing tab character. The default value is 4.

pub fn set_hard_tab_indent(&mut self, enabled: bool)

Set if a hard tab is used or not for indent. When true is set, typing a tab key inserts a hard tab instead of spaces. By default, hard tab is disabled.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

textarea.set_hard_tab_indent(true);
textarea.insert_tab();
assert_eq!(textarea.lines(), ["\t"]);

pub fn hard_tab_indent(&self) -> bool

Get if a hard tab is used for indent or not.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

assert!(!textarea.hard_tab_indent());
textarea.set_hard_tab_indent(true);
assert!(textarea.hard_tab_indent());

pub fn indent(&self) -> &'static str

Get a string for indent. It consists of spaces by default. When hard tab is enabled, it is a tab character.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

assert_eq!(textarea.indent(), "    ");
textarea.set_tab_length(2);
assert_eq!(textarea.indent(), "  ");
textarea.set_hard_tab_indent(true);
assert_eq!(textarea.indent(), "\t");

pub fn set_max_histories(&mut self, max: usize)

Set how many modifications are remembered for undo/redo. Setting 0 disables undo/redo.

pub fn max_histories(&self) -> usize

Get how many modifications are remembered for undo/redo. The default value is 50.

pub fn set_cursor_line_style(&mut self, style: Style)

Set the style of line at cursor. By default, the cursor line is styled with underline. To stop styling the cursor line, set the default style.

use ratatui_core::style::{Style, Color};
use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

let style = Style::default().fg(Color::Red);
textarea.set_cursor_line_style(style);
assert_eq!(textarea.cursor_line_style(), style);

// Disable cursor line style
textarea.set_cursor_line_style(Style::default());

pub fn cursor_line_style(&self) -> Style

Get the style of cursor line. By default it is styled with underline.

pub fn set_line_number_style(&mut self, style: Style)

Set the style of line number. By setting the style with this method, line numbers are drawn in textarea, meant that line numbers are disabled by default. If you want to show line numbers but don’t want to style them, set the default style.

use ratatui_core::style::{Style, Color};
use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

// Show line numbers in dark gray background
let style = Style::default().bg(Color::DarkGray);
textarea.set_line_number_style(style);
assert_eq!(textarea.line_number_style(), Some(style));

pub fn remove_line_number(&mut self)

Remove the style of line number which was set by TextArea::set_line_number_style. After calling this method, Line numbers will no longer be shown.

use ratatui_core::style::{Style, Color};
use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

textarea.set_line_number_style(Style::default().bg(Color::DarkGray));
textarea.remove_line_number();
assert_eq!(textarea.line_number_style(), None);

pub fn line_number_style(&self) -> Option<Style>

Get the style of line number if set.

pub fn line_number_width(&self) -> u16

Get the width in columns of the line number gutter: the digits of the last line number plus one margin column on each side. It is 0 when line numbers are not enabled. Text is drawn to the right of the gutter, so this is the offset to subtract when converting a column within the rendered area into a text column for TextArea::screen_to_data.

use ratatui_core::style::Style;
use ratatui_textarea::TextArea;

let mut textarea: TextArea = (1..=10).map(|i| i.to_string()).collect();
assert_eq!(textarea.line_number_width(), 0);

textarea.set_line_number_style(Style::default());
assert_eq!(textarea.line_number_width(), 4); // "10" plus a margin on each side

pub fn set_placeholder_text(&mut self, placeholder: impl Into<String>)

Set the placeholder text. The text is set in the textarea when no text is input. Setting a non-empty string "" enables the placeholder. The default value is an empty string so the placeholder is disabled by default. To customize the text style, see TextArea::set_placeholder_style.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();
assert_eq!(textarea.placeholder_text(), "");
assert!(textarea.placeholder_style().is_none());

textarea.set_placeholder_text("Hello");
assert_eq!(textarea.placeholder_text(), "Hello");
assert!(textarea.placeholder_style().is_some());

pub fn set_placeholder_style(&mut self, style: Style)

Set the style of the placeholder text. The default style is a dark gray text.

use ratatui_core::style::{Style, Color};
use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();
assert_eq!(textarea.placeholder_style(), None); // When the placeholder is disabled

textarea.set_placeholder_text("Enter your message"); // Enable placeholder by setting non-empty text

let style = Style::default().bg(Color::Blue);
textarea.set_placeholder_style(style);
assert_eq!(textarea.placeholder_style(), Some(style));

pub fn placeholder(&self) -> &Text<'_>

Get the placeholder. The placeholder is shown when the textarea is empty.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();
textarea.set_styled_placeholder("Hello");
assert_eq!(textarea.placeholder().lines[0].spans[0].content, "Hello");

pub fn set_styled_placeholder(&mut self, placeholder: impl Into<Text<'a>>)

Set the placeholder as a styled ratatui_core::text::Text value. The placeholder is shown when the textarea is empty. Accepts anything that converts into Text: a plain &str, a styled Line, or a full Text.

To disable the placeholder, pass an empty Text: textarea.set_styled_placeholder(Text::default()). Alternatively, set_placeholder_text called with "" also clears it.

use ratatui_core::style::{Color, Style, Stylize};
use ratatui_core::text::{Line, Span, Text};
use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

// Plain string
textarea.set_styled_placeholder("Enter your message");
assert!(!textarea.placeholder().lines.is_empty());

// Styled span
textarea.set_styled_placeholder(Line::from(vec![
    Span::styled("Required: ", Style::default().fg(Color::Red)),
    Span::raw("enter your name"),
]));

// Multi-line Text
textarea.set_styled_placeholder(Text::from_iter([
    Line::raw("Line 1"),
    Line::raw("Line 2"),
]));

pub fn placeholder_text(&self) -> &str

Get the placeholder text. An empty string means the placeholder is disabled. The default value is an empty string.

use ratatui_textarea::TextArea;

let textarea = TextArea::default();
assert_eq!(textarea.placeholder_text(), "");

pub fn placeholder_style(&self) -> Option<Style>

Get the placeholder style. When the placeholder text is empty, it returns None since the placeholder is disabled. The default style is a dark gray text.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();
assert_eq!(textarea.placeholder_style(), None);

textarea.set_placeholder_text("hello");
assert!(textarea.placeholder_style().is_some());

pub fn set_mask_char(&mut self, mask: char)

Specify a character masking the text. All characters in the textarea will be replaced by this character. This API is useful for making a kind of credentials form such as a password input.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

textarea.set_mask_char('*');
assert_eq!(textarea.mask_char(), Some('*'));
textarea.set_mask_char('●');
assert_eq!(textarea.mask_char(), Some('●'));

pub fn clear_mask_char(&mut self)

Clear the masking character previously set by TextArea::set_mask_char.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

textarea.set_mask_char('*');
assert_eq!(textarea.mask_char(), Some('*'));
textarea.clear_mask_char();
assert_eq!(textarea.mask_char(), None);

pub fn mask_char(&self) -> Option<char>

Get the character to mask text. When no character is set, None is returned.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

assert_eq!(textarea.mask_char(), None);
textarea.set_mask_char('*');
assert_eq!(textarea.mask_char(), Some('*'));

pub fn set_cursor_style(&mut self, style: Style)

Set the style of cursor. By default, a cursor is rendered in the reversed color. Setting the same style as cursor line hides a cursor.

use ratatui_core::style::{Style, Color};
use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

let style = Style::default().bg(Color::Red);
textarea.set_cursor_style(style);
assert_eq!(textarea.cursor_style(), style);

pub fn cursor_style(&self) -> Style

Get the style of cursor.

pub fn lines(&'a self) -> &'a [String]

Get slice of line texts. This method borrows the content, but not moves. Note that the returned slice will never be empty because an empty text means a slice containing one empty line. This is correct since any text file must end with a newline.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();
assert_eq!(textarea.lines(), [""]);

textarea.insert_char('a');
assert_eq!(textarea.lines(), ["a"]);

textarea.insert_newline();
assert_eq!(textarea.lines(), ["a", ""]);

textarea.insert_char('b');
assert_eq!(textarea.lines(), ["a", "b"]);

pub fn cursor(&self) -> DataCursor

Get the current cursor position. 0-base character-wise (row, col) cursor position.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();
assert_eq!(textarea.cursor(), (0, 0));

textarea.insert_char('a');
textarea.insert_newline();
textarea.insert_char('b');

assert_eq!(textarea.cursor(), (1, 1));

pub fn screen_cursor(&self) -> ScreenCursor

pub fn scroll_offset(&self) -> (u16, u16)

Get the scroll position as a 0-base (row, col) pair: the display line and column drawn at the top-left of the rendered area.

Display lines are counted after soft wrapping, so with WrapMode::None a display line is a line of the text and otherwise a long line spans several. This is the offset that turns a position within the rendered area into the screen position TextArea::screen_to_data expects.

The value is recorded while rendering, so it is (0, 0) until the widget has been drawn at least once.

use ratatui_core::buffer::Buffer;
use ratatui_core::layout::Rect;
use ratatui_core::widgets::Widget as _;
use ratatui_textarea::{CursorMove, TextArea};

let mut textarea: TextArea = (0..20).map(|i| i.to_string()).collect();
assert_eq!(textarea.scroll_offset(), (0, 0));

// The viewport follows the cursor while drawing.
textarea.move_cursor(CursorMove::Bottom);
let area = Rect { x: 0, y: 0, width: 8, height: 4 };
(&textarea).render(area, &mut Buffer::empty(area));

let (row, _) = textarea.scroll_offset();
assert_eq!(row, 16, "the last four lines are on screen");

pub fn screen_to_data(&self, row: usize, col: usize) -> DataCursor

Convert a screen position into the position in the text drawn there, accounting for soft wrapping and tab expansion.

This is the mapping a mouse click needs. row and col are 0-base display coordinates counted from the top-left of the text, not of the rendered area — add TextArea::scroll_offset to coordinates taken from the area the widget was drawn into, and subtract TextArea::line_number_width from the column when line numbers are enabled.

Positions outside the text clamp rather than being rejected: a row past the last display line resolves to that line, and a column past the end of a line resolves to its end. A click below or to the right of the text therefore lands where a reader would expect.

use ratatui_textarea::{CursorMove, DataCursor, TextArea};

let mut textarea = TextArea::from(["hello", "world"]);
assert_eq!(textarea.screen_to_data(1, 3), DataCursor(1, 3));

// Below the text clamps to the last line.
assert_eq!(textarea.screen_to_data(99, 0), DataCursor(1, 0));

// Move the cursor to a clicked position.
let clicked = textarea.screen_to_data(0, 2);
textarea.move_cursor(CursorMove::Jump(clicked.0 as u16, clicked.1 as u16));
assert_eq!(textarea.cursor(), (0, 2));

pub fn selection_range(&self) -> Option<((usize, usize), (usize, usize))>

Get the current selection range as a pair of the start position and the end position. The range is bounded inclusively below and exclusively above. The positions are 0-base character-wise (row, col) values. The first element of the pair is always smaller than the second one even when it is ahead of the cursor. When no text is selected, this method returns None.

use ratatui_textarea::TextArea;
use ratatui_textarea::CursorMove;

let mut textarea = TextArea::from([
    "aaa",
    "bbb",
    "ccc",
]);

// It returns `None` when the text selection is not ongoing
assert_eq!(textarea.selection_range(), None);

textarea.start_selection();
assert_eq!(textarea.selection_range(), Some(((0, 0), (0, 0))));

textarea.move_cursor(CursorMove::Forward);
assert_eq!(textarea.selection_range(), Some(((0, 0), (0, 1))));

textarea.move_cursor(CursorMove::Down);
assert_eq!(textarea.selection_range(), Some(((0, 0), (1, 1))));

// Start selection at (1, 1)
textarea.cancel_selection();
textarea.start_selection();

// The first element of the pair is always smaller than the second one
textarea.move_cursor(CursorMove::Back);
assert_eq!(textarea.selection_range(), Some(((1, 0), (1, 1))));

pub fn set_alignment(&mut self, alignment: HorizontalAlignment)

Set text alignment. When Alignment::Center or Alignment::Right is set, line number is automatically disabled because those alignments don’t work well with line numbers.

use ratatui_core::layout::Alignment;
use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

textarea.set_alignment(Alignment::Center);
assert_eq!(textarea.alignment(), Alignment::Center);

pub fn alignment(&self) -> HorizontalAlignment

Get current text alignment. The default alignment is Alignment::Left.

use ratatui_core::layout::Alignment;
use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

assert_eq!(textarea.alignment(), Alignment::Left);

pub fn set_wrap_mode(&mut self, mode: WrapMode)

Set the soft-wrap mode used when rendering text.

pub fn wrap_mode(&self) -> WrapMode

Get the current soft-wrap mode.

pub fn is_empty(&self) -> bool

Check if the textarea has a empty content.

use ratatui_textarea::TextArea;

let textarea = TextArea::default();
assert!(textarea.is_empty());

let textarea = TextArea::from(["hello"]);
assert!(!textarea.is_empty());

pub fn yank_text(&self) -> String

Get the yanked text. Text is automatically yanked when deleting strings by TextArea::delete_line_by_head, TextArea::delete_line_by_end, TextArea::delete_word, TextArea::delete_next_word, TextArea::delete_str, TextArea::copy, and TextArea::cut. When multiple lines were yanked, they are always joined with \n.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::from(["abc"]);
textarea.delete_next_word();
assert_eq!(textarea.yank_text(), "abc");

// Multiple lines are joined with \n
let mut textarea = TextArea::from(["abc", "def"]);
textarea.delete_str(5);
assert_eq!(textarea.yank_text(), "abc\nd");

pub fn set_yank_text(&mut self, text: impl Into<String>)

Set a yanked text. The text can be inserted by TextArea::paste. \n and \r\n are recognized as newline but \r isn’t.

use ratatui_textarea::TextArea;

let mut textarea = TextArea::default();

textarea.set_yank_text("hello\nworld");
textarea.paste();
assert_eq!(textarea.lines(), ["hello", "world"]);

pub fn scroll(&mut self, scrolling: impl Into<Scrolling>)

Scroll the textarea. See Scrolling for the argument. The cursor will not move until it goes out the viewport. When the cursor position is outside the viewport after scroll, the cursor position will be adjusted to stay in the viewport using the same logic as CursorMove::InViewport.

use ratatui_textarea::TextArea;

// Let's say terminal height is 8.

// Create textarea with 20 lines "0", "1", "2", "3", ...
let mut textarea: TextArea = (0..20).into_iter().map(|i| i.to_string()).collect();

// Scroll down by 15 lines. Since terminal height is 8, cursor will go out
// the viewport.
textarea.scroll((15, 0));
// So the cursor position was updated to stay in the viewport after the scrolling.
assert_eq!(textarea.cursor(), (15, 0));

// Scroll up by 5 lines. Since the scroll amount is smaller than the terminal
// height, cursor position will not be updated.
textarea.scroll((-5, 0));
assert_eq!(textarea.cursor(), (15, 0));

// Scroll up by 5 lines again. The terminal height is 8. So a cursor reaches to
// the top of viewport after scrolling up by 7 lines. Since we have already
// scrolled up by 5 lines, scrolling up by 5 lines again makes the cursor overrun
// the viewport by 5 - 2 = 3 lines. To keep the cursor stay in the viewport, the
// cursor position will be adjusted from line 15 to line 12.
textarea.scroll((-5, 0));
assert_eq!(textarea.cursor(), (12, 0));

Trait Implementations

impl<'a> Clone for CustomTextArea<'a>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Deref for CustomTextArea<'a>

type Target = TextArea<'a>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a> DerefMut for CustomTextArea<'a>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'a> Widget for &CustomTextArea<'a>

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.