Text entry

Single-line input, multi-line textarea, dropdown select, filterable combobox, and multi-select with checkboxes.

Input

A single-line text field with cursor, horizontal scrolling, selection, history, and optional validation or autocomplete.

extern crate tuile;
extern crate ratatui_core;
use tuile::prelude::*;

fn demo(area: Rect, buf: &mut Buffer) {
let mut state = InputState::new();
Input::new()
    .placeholder("Name")
    .focused(true)
    .render(area, buf, &mut state);

if state.take_submitted() {
    let value = state.value();
}
}
fn main() {}

State

InputState owns:

Create state with InputState::new() or InputState::with_value("text"). Read the value with state.value(), set it with state.set_value("text"), or select all with state.select_all().

Keys

Mouse

Click positions the cursor. Drag selects text. The widget tracks double-click timing but full text selection on double-click depends on the render implementation.

Options

The restrict option filters typed characters. Digits allows only 0-9. Integer allows digits and leading -. Number allows digits, ., -, +, e, E. Alpha allows letters. Alnum allows letters and digits. Custom uses a custom filter function passed to state.custom_filter.

TextArea

A multi-line text editor with line numbers, syntax highlighting hook, undo/redo, and scrolling.

extern crate tuile;
extern crate ratatui_core;
use tuile::prelude::*;

fn demo(area: Rect, buf: &mut Buffer) {
let mut state = TextAreaState::new();
TextArea::new()
    .line_numbers(true)
    .highlight_line(true)
    .focused(true)
    .render(area, buf, &mut state);

let text = state.text();
}
fn main() {}

State

TextAreaState owns:

Create state with TextAreaState::new() or TextAreaState::with_text("multi\nline"). Read all text with state.text(), set it with state.set_text("text"), or insert at cursor with state.insert_str("text"). The undo and redo stacks store up to 100 snapshots each.

Keys

Mouse

Click positions the cursor. Drag selects a rectangular region. Wheel scrolls vertically.

Options

The highlighter hook is called once per visible line with the line text. Return a list of (start_byte, end_byte, Style) tuples. The showcase page includes a simple Rust highlighter that matches keywords and strings.

Cursor styles

CursorStyle controls how the cursor is drawn:

Select

A dropdown with a fixed list of options. Click or press Space/Enter to open, arrow keys to navigate, Enter to choose.

extern crate tuile;
extern crate ratatui_core;
use tuile::prelude::*;

fn demo(area: Rect, buf: &mut Buffer) {
let mut state = SelectState::new(&["Red", "Green", "Blue"]);
Select::new()
    .placeholder("Pick a color")
    .focused(true)
    .render(area, buf, &mut state);

if let Some(idx) = state.selected() {
    let label = state.selected_label().unwrap();
}
}
fn main() {}

State

SelectState owns:

Create state with SelectState::new(&["A", "B", "C"]) or SelectState::with_options(vec). Read selection with state.selected() or state.selected_label(). Set selection with state.set_selected(Some(idx)) or clear with state.set_selected(None). Close the dropdown with state.close().

Each SelectOption has a label (displayed text), optional value (stored data), and disabled flag.

Keys

When closed:

When open:

Mouse

Click the field to open or close. Click an option to select it. Wheel scrolls the dropdown list. Click outside closes the dropdown (the parent must handle this by checking state.dropdown_area and calling state.close()).

Options

Set state.dropdown_width to control dropdown width. DropdownWidth::Auto fits the longest option. DropdownWidth::Field matches the field width. DropdownWidth::Fixed(w) uses a fixed width.

Combobox

An editable select: type to filter options, arrow keys to navigate, Enter to choose. The input buffer filters the list in real time.

extern crate tuile;
extern crate ratatui_core;
use tuile::prelude::*;

fn demo(area: Rect, buf: &mut Buffer) {
let mut state = ComboboxState::new(&["Rust", "Python", "JavaScript"]);
Combobox::new()
    .placeholder("Type to filter")
    .focused(true)
    .render(area, buf, &mut state);

if let Some(idx) = state.selected() {
    let label = state.selected_label().unwrap();
}
}
fn main() {}

State

ComboboxState owns:

Create state with ComboboxState::new(&["A", "B"]). The filtered list is rebuilt on every keystroke, case-insensitive substring matching. Read selection with state.selected() or state.selected_label(). The input buffer is cleared when an option is selected.

Keys

Mouse

Same as Select: click to open/close, click an option to select, wheel scrolls.

Options

MultiSelect

A select with checkboxes. Space toggles the highlighted option, Enter confirms and closes. The state tracks a set of selected indices.

extern crate tuile;
extern crate ratatui_core;
use tuile::prelude::*;

fn demo(area: Rect, buf: &mut Buffer) {
let mut state = MultiSelectState::new(&["HTML", "CSS", "JS"]);
MultiSelect::new()
    .placeholder("Select multiple")
    .focused(true)
    .render(area, buf, &mut state);

let selected = state.selected_indices();
let summary = state.summary();
}
fn main() {}

State

MultiSelectState owns:

Create state with MultiSelectState::new(&["A", "B"]). Read selections with state.selected_indices() (returns Vec<usize> of selected indices) or state.summary() (returns "2 selected").

Keys

When closed:

When open:

Mouse

Click the field to open. Click a checkbox to toggle that option. Click outside closes (the parent must handle this).

Options

FieldShape

The FieldShape enum controls the frame drawn around text fields. All five widgets in this chapter accept shape(s) as a builder option. The default is Tall(Edge::Full), a Textual-style frame with thick side bars and thin top and bottom lines.

The edge parameter controls bar thickness for Tall, Bars, and Bar:

For example, shape(FieldShape::Bar(Edge::Hair)) draws a thin left accent bar. shape(FieldShape::Prompt) removes the frame entirely and draws a ❯ prompt.

Choosing between Select, Combobox, and MultiSelect

Use Select when:

• The list is short (under 20 options) and the user knows what they want.
• Typing is slower than arrow keys (e.g. “United States” vs. typing “uni”).
• The list is stable and well-known (countries, months, enum values).

Use Combobox when:

• The list is long (50+ options) and typing is faster than scrolling.
• The user may not know the exact label (search by substring).
• The list is dynamic or fetched from a search API.

Use MultiSelect when:

• The user needs to choose zero or more options.
• The choices are independent (tags, permissions, features).
• You want a compact summary like “3 selected” instead of showing all chosen items.

If the user must pick exactly one from a long list and knows what they want, Combobox is the right choice. If they may not remember the label, Combobox lets them filter. If they need to pick several, MultiSelect is the only option in this family.