Struct TextArea 

pub struct TextArea { /* private fields */ }

A multi-line text input.

Implementations

impl TextArea

pub fn new(value: impl Into<Arc<str>>) -> Self

Create a new text area.

pub fn bound(state: &TextEditor) -> Self

Create a new text area bound to a TextEditor state bundle.

pub fn value(self, value: impl Into<Arc<str>>) -> Self

Set the text content.

pub fn placeholder(self, placeholder: impl Into<Arc<str>>) -> Self

Set placeholder text (shown when empty).

pub fn cursor(self, cursor: usize) -> Self

Set cursor position.

pub fn anchor(self, anchor: Option<usize>) -> Self

Set selection anchor position (byte index). When set, text between anchor and cursor is selected.

pub fn bind(self, state: &TextEditor) -> Self

Bind the text area’s value, cursor, and anchor from a TextEditor state bundle.

pub fn line_numbers(self, show: bool) -> Self

Show line numbers.

pub fn line_number_mode(self, mode: TextAreaLineNumberMode) -> Self

Set line-number display mode for the built-in gutter.

Use TextAreaLineNumberMode::Relative for Vim-style relative numbers: the cursor’s logical line shows its absolute number, while lines above and below show their distance from the cursor line.

pub fn min_line_number_width(self, width: u8) -> Self

Set minimum line number width (number of digits to reserve).

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

Enable word wrapping.

pub fn color_strategy( self, strategy: impl TextAreaColorStrategy + 'static, ) -> Self

Set text coloring strategy.

pub fn language(self, language: impl Into<Arc<str>>) -> Self

Set language identifier for coloring strategies.

pub fn language_from_path(self, path: impl AsRef<Path>) -> Self

Set language identifier by resolving from a file path’s extension or name.

Uses the default syntect syntax definitions. If no syntax matches the path, the language remains unset (plain text fallback). TypeScript/TSX paths fall back to JavaScript/JSX-compatible syntaxes when the default set does not provide exact grammars.

pub fn theme(self, theme: impl Into<Arc<str>>) -> Self

Set theme identifier for coloring strategies.

pub fn with_syntax( self, language: impl Into<Arc<str>>, theme: impl Into<Arc<str>>, ) -> Self

Enable syntect-based syntax highlighting with default strategy.

pub fn with_syntax_bg( self, language: impl Into<Arc<str>>, theme: impl Into<Arc<str>>, ) -> Self

Enable syntect-based syntax highlighting with theme background colors.

pub fn with_syntax_custom_theme( self, language: impl Into<Arc<str>>, theme_name: impl Into<Arc<str>>, tm_theme_xml: impl AsRef<str>, ) -> Result<Self>

Enable syntect-based syntax highlighting with a custom theme string.

pub fn with_syntax_custom_theme_bytes( self, language: impl Into<Arc<str>>, theme_name: impl Into<Arc<str>>, bytes: impl AsRef<[u8]>, ) -> Result<Self>

Enable syntect-based syntax highlighting with custom theme bytes.

pub fn with_syntax_custom_theme_from_file( self, language: impl Into<Arc<str>>, theme_name: impl Into<Arc<str>>, path: impl AsRef<Path>, ) -> Result<Self>

Enable syntect-based syntax highlighting with a custom theme file.

pub fn with_syntax_strategy( self, strategy: SyntectStrategy, language: impl Into<Arc<str>>, theme: impl Into<Arc<str>>, ) -> Self

Enable syntect-based syntax highlighting with a custom strategy.

pub fn style(self, style: Style) -> Self

Set base style.

pub fn hover_style(self, style: Style) -> Self

Set style when hovered.

pub fn extend_hover_style(self, style: Style) -> Self

Extend the active theme’s hover style with additional fields.

pub fn inherit_hover_style(self) -> Self

Inherit hover style from the active theme.

pub fn hover_style_slot(self, slot: StyleSlot) -> Self

Set hover style slot directly for composite forwarding.

pub fn focus_style(self, style: Style) -> Self

Set focus chrome style.

pub fn extend_focus_style(self, style: Style) -> Self

Extend the active theme’s focus style with additional fields.

pub fn inherit_focus_style(self) -> Self

Inherit focus style from the active theme.

pub fn focus_style_slot(self, slot: StyleSlot) -> Self

Set focus style slot directly for composite forwarding.

pub fn focus_content_style(self, style: Style) -> Self

Set focused content text style.

pub fn hover_border_style(self, border_style: BorderStyle) -> Self

Set border style when hovered.

pub fn caret_shape(self, shape: CaretShape) -> Self

Set caret shape.

pub fn caret_color(self, color: Color) -> Self

Set caret color (only used for block caret rendering).

pub fn selection_style(self, style: Style) -> Self

Set selection highlight style.

pub fn extend_selection_style(self, style: Style) -> Self

Extend the active theme’s selection style with additional fields.

pub fn inherit_selection_style(self) -> Self

Inherit selection style from the active theme.

pub fn selection_style_slot(self, slot: StyleSlot) -> Self

Set selection style slot directly for composite forwarding.

pub fn show_selection_when_unfocused(self, show: bool) -> Self

Show the active selection range while the text area is unfocused.

Enabled by default so keyboard/programmatic focus changes preserve the visible selection, matching DocumentView. Pass false to hide inactive selections.

pub fn unfocused_selection_style(self, style: Style) -> Self

Set selection highlight style while unfocused.

pub fn inherit_unfocused_selection_style(self) -> Self

Inherit unfocused selection style from the active theme.

pub fn unfocused_selection_style_slot(self, slot: StyleSlot) -> Self

Set unfocused selection style slot directly for composite forwarding.

pub fn placeholder_style(self, style: Style) -> Self

Set placeholder style.

pub fn focus_placeholder_style(self, style: Style) -> Self

Set placeholder style when focused.

pub fn line_number_style(self, style: Style) -> Self

Set line number style.

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

Set border.

pub fn border_style(self, style: BorderStyle) -> Self

Set border style.

pub fn padding(self, padding: impl Into<Padding>) -> Self

Set padding.

pub fn width(self, width: Length) -> Self

Set width.

pub fn height(self, height: Length) -> Self

Set height.

pub fn on_change(self, cb: Callback<TextAreaEvent>) -> Self

Set on-change callback.

pub fn on_edit(self, cb: Callback<TextEditEvent>) -> Self

Set on-edit callback.

pub fn on_editor_state_change( self, cb: Callback<TextAreaStateChangeEvent>, ) -> Self

Set a single reason-tagged editor-state callback.

pub fn on_click(self, cb: Callback<MouseEvent>) -> Self

Set on-click callback.

pub fn on_key(self, handler: KeyHandler) -> Self

Set on-key handler.

pub fn key_interceptor(self, handler: KeyHandler) -> Self

Set a pre-insertion key interceptor.

This handler runs after clipboard shortcuts but before newline insertion, tab expansion, or regular text editing. If it returns true, the key is consumed and neither the editor nor on_key will fire.

pub fn clear_bindings(self, bindings: KeyBindings) -> Self

Set widget-level single-key bindings that clear the text area.

Multi-step chord entries in bindings are ignored by the per-key text area handler.

pub fn vim_motions(self, enabled: bool) -> Self

Enable or disable TextArea-only Vim-style modal motions.

Disabled by default. When enabled, the TextArea starts in normal mode.

pub fn vim_keymap(self, keymap: TextAreaVimKeymap) -> Self

Set widget-local Vim key remaps.

Remaps are only applied while Vim motions are enabled and the TextArea is not in insert mode. They translate matching keys to canonical Vim command characters before command dispatch.

pub fn vim_config(self, config: TextAreaVimConfig) -> Self

Set Vim-specific rendering options such as search feedback and current-line highlighting.

pub fn vim_current_line_highlight( self, mode: TextAreaVimCurrentLineHighlight, ) -> Self

Convenience builder for Vim current-line highlighting.

Pass TextAreaVimCurrentLineHighlight::Full to include the gutter and line numbers, or TextAreaVimCurrentLineHighlight::Content to affect only the text content area.

pub fn highlight_vim_current_line(self, enabled: bool) -> Self

Toggle full-row Vim current-line highlighting.

pub fn on_vim_mode_change(self, cb: Callback<TextAreaVimMode>) -> Self

Observe internal Vim mode changes for status bars or mode-aware styling.

pub fn on_image_paste(self, cb: Callback<ImageContent>) -> Self

Set callback invoked when an image is pasted via Ctrl+Shift+I.

pub fn images(self, images: Vec<ImageContent>) -> Self

Set the ordered list of images associated with this text area.

pub fn on_images_change(self, cb: Callback<Vec<ImageContent>>) -> Self

Set callback invoked when the images list changes (e.g. image pasted, sentinel deleted).

pub fn image_mode(self, mode: TextAreaImageMode) -> Self

Set the image display mode (Inline or Attachment).

pub fn image_placeholder(self, label: impl Into<Arc<str>>) -> Self

Set the placeholder label rendered for each inline image sentinel (default: "[Image]").

pub fn image_placeholder_style(self, style: Style) -> Self

Set the style for inline image placeholder labels.

pub fn image_placeholder_focus_style(self, style: Style) -> Self

Set the style for inline image placeholder labels when the widget is focused.

pub fn image_placeholder_hover_style(self, style: Style) -> Self

Set the hover style patched over inline image placeholder labels.

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

Set disabled.

pub fn disabled_style(self, style: Style) -> Self

Set disabled style.

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

Set read-only mode. Allows mouse selection but blocks keyboard input.

pub fn multi_click_select(self, enabled: bool) -> Self

Enable or disable word/line selection on double/triple click.

When false, double and triple clicks behave as single clicks (no word or line selection). Drag-to-select remains unaffected.

pub fn triple_click_mode(self, mode: TripleClickSelectionMode) -> Self

Set how triple-click expands selection.

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

Set focusable.

pub fn newline_binding(self, binding: TextAreaNewlineBinding) -> Self

Override app-level newline key policy for this TextArea only.

pub fn tab_width(self, width: u8) -> Self

When set to a non-zero value, pressing Tab inserts spaces up to the next tab stop (aligning to a multiple of width columns) instead of moving focus.

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

When true, Tab inserts a tab character instead of moving focus.

pub fn tab_stop(self, tab_stop: u8) -> Self

Display width of a literal \t character. \t advances to the next multiple of this value, measured from the logical line start.

Defaults to 8 (terminal convention). Set to 0 to render \t as zero columns (rarely useful — mostly for parity with unicode-width).

pub fn scroll_offset(self, offset: usize) -> Self

Set scroll offset (line index).

pub fn scroll_to_line(self, line: usize) -> Self

Scroll to a zero-based logical/source line.

When wrapping is enabled, this resolves to the first visual row for the requested logical line. If the logical line is beyond the available text, reconciliation clamps to the last available visual row / maximum offset.

pub fn scroll_behavior(self, behavior: ScrollBehavior) -> Self

Set how explicit line scroll targets are applied.

This affects Self::scroll_to_line only; controlled offsets and cursor auto-scroll remain immediate.

pub fn scroll_transition(self, transition: TransitionConfig) -> Self

Animate explicit line scroll targets with transition.

pub fn scroll_wheel(self, enabled: bool) -> Self

Enable mouse wheel scrolling.

pub fn scroll_wheel_multiplier(self, multiplier: u16) -> Self

Override the app-wide mouse wheel step multiplier for this text area.

pub fn on_scroll(self, cb: Callback<ScrollEvent>) -> Self

Set on-scroll callback.

pub fn on_scroll_to(self, cb: Callback<usize>) -> Self

Set on-scroll-to callback (for scrollbar dragging).

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

Enable scrollbar.

pub fn scrollbar_config(self, config: ScrollbarConfig) -> Self

Set scrollbar configuration.

pub fn gutter_lines(self, lines: Arc<Vec<Vec<Span>>>, col_width: u16) -> Self

Set a custom gutter column.

lines is indexed by logical line (0-based). Continuation visual lines (word-wrap overflow) show an empty gutter. col_width is the fixed column width reserved for the gutter; when > 0 it overrides the line_numbers gutter width everywhere.

pub fn gutter(self, gutter: TextAreaGutter) -> Self

Set a composable gutter. Compatibility fields are lowered for the current renderer.

pub fn gutter_inset(self, inset: u16) -> Self

Reserve empty cells before the gutter / line numbers.

pub fn copy_excluded_bytes(self, ranges: Arc<Vec<(usize, usize)>>) -> Self

Set byte ranges in value to exclude from clipboard copy.

pub fn clipboard_transform( self, transform: Arc<dyn for<'a> Fn(TextAreaClipboardTransformEvent<'a>) -> String>, ) -> Self

Set an opt-in transform for selected text immediately before clipboard copy/cut.

By default, TextArea copies the rendered selection unchanged.

pub fn selection_excluded_lines(self, lines: Arc<Vec<usize>>) -> Self

Set 0-based logical line indices whose selection newline highlight is suppressed.

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

Enable horizontal scrollbar (only effective when wrap is disabled).

pub fn h_scrollbar_variant(self, style: ScrollbarVariant) -> Self

Set horizontal scrollbar rendering style (integrated into border vs standalone row).

pub fn h_scrollbar_thumb(self, ch: char) -> Self

Set custom horizontal scrollbar thumb character (default: ‘█’).

pub fn sentinels(self, sentinels: Vec<TextAreaSentinel>) -> Self

Set the ordered list of custom inline sentinels.

pub fn on_sentinels_change(self, cb: Callback<Vec<TextAreaSentinel>>) -> Self

Set callback invoked when the sentinels list changes (a sentinel was deleted).

pub fn on_sentinel_event(self, cb: Callback<Vec<SentinelEvent>>) -> Self

Callback for sentinel lifecycle (e.g. user-deleted token with stable id).

pub fn on_sentinel_click(self, cb: Callback<TextAreaSentinelClickEvent>) -> Self

Callback invoked when an inline image or custom sentinel placeholder is clicked.

pub fn decoration(self, decoration: TextAreaDecoration) -> Self

Add a byte-range decoration.

pub fn decorations( self, decorations: impl IntoIterator<Item = TextAreaDecoration>, ) -> Self

Add byte-range decorations.

pub fn virtual_text(self, virtual_text: TextAreaVirtualText) -> Self

Add non-editable virtual text rendered inline or at end-of-line.

pub fn virtual_texts( self, virtual_texts: impl IntoIterator<Item = TextAreaVirtualText>, ) -> Self

Add non-editable virtual text entries.

pub fn on_text_paste(self, cb: Callback<TextAreaPasteEvent>) -> Self

Handle pasted text before the default insertion path.

When set, the callback receives the pasted text plus the current cursor/selection and the text area does not insert the text itself.

Trait Implementations

impl Clone for TextArea

fn clone(&self) -> TextArea

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for TextArea

fn default() -> Self

Returns the “default value” for a type.

impl From<TextArea> for Element

fn from(value: TextArea) -> Self

Converts to this type from the input type.