Documentation menu

text_field

Edit Unicode text with retained caret, selection, wrapping, composition, and optional rich formatting.

Use text_field(binding: Binding<EditBuffer>) -> BoundTextField when the user needs to edit content rather than only display it. Its EditBuffer holds the text together with selection, composition, formatting, and undo history, giving the field a complete editing model across reevaluations.

Editor Construction

use hera_kit::{EditBuffer, View, ViewExt, text_field, view_fn};

fn editor() -> Result<impl View, hera_kit::EditError> {
    let initial = EditBuffer::new("")?;
    Ok(view_fn(move |cx| {
        let document = cx.state("document", || initial.clone());
        Ok(text_field(document)
            .multi_line()
            .fill_width()
            .height(180.0)
            .font_size(16.0)
            .padding(12.0))
    }))
}

The example initializes the editing model once for the mounted view and passes its binding to the field. When the application needs to apply or save the edit, read committed_text() from that model. The field itself retains the focus, caret, selection geometry, and viewport state needed for interaction.

Sizing and Wrapping

The default single-line field scrolls horizontally as needed. Calling .multi_line() enables hard line breaks and viewport wrapping, while sizing remains configurable separately: .fill_width() uses the offered width, and .width(value) requests a preferred width that can shrink under parent constraints. A width call after fill-width switches back to preferred-width sizing.

For multiline content, choose TextWrap::Viewport to wrap within the current viewport or TextWrap::Fixed(width) to use a fixed text width. TextWrap::None preserves hard breaks while allowing horizontal scrolling. The default multiline height is 120 logical pixels, which can be changed independently of that wrapping policy.

Resize reflows text and recomputes caret and highlight geometry together without replacing the model or focus.

Selection and Navigation

Selection follows the shaped text through clicks, drags, and Shift extension. Because caret positions use shaped grapheme stops, navigation can handle bidirectional text without treating each UTF-8 byte as a visual position. Dragging beyond a narrow viewport reveals more text as the selection endpoint moves.

Multiline fields consume vertical wheel movement within their accepted extents and pass unused movement to an enclosing scroll container. Scrolling preserves selection; typing, navigation, and clicking resume caret reveal.

Text Formatting

Enable .formatting(true) when the model should retain rich styling as part of the edit. EditBuffer then provides bold and underline toggles, selection style, and format spans whose changes participate in undo/redo and Unicode editing. Formatted fields also support Ctrl+B and Ctrl+U through the same editing model.

Use matching registered font families on the client and daemon. Bold uses actual registered faces; underlines are represented with retained rectangle nodes.

Text Service Integration

For composition and other text-service input, AppHost::with_text_input attaches a bounded local service and returns a TextInputClient. Preserve its session identity when delivering requests so an old composition cannot reach a different field. This local editing connection operates alongside the server's separate surface keyboard ownership.

See text internals and input internals.

Component-Specific Reference

These methods configure BoundTextField, the rebuildable description returned by text_field(binding), and return Self. The default description is single-line, with a preferred width of 240 logical pixels, font key zero, a font size of 16, and formatting disabled.

MethodPurpose
fontSelects the registered editing font.
font_sizeSets the logical font size.
formattingEnables persistent rich-text formatting.
widthSets a preferred viewport width.
fill_widthUses the finite offered viewport width.
multi_lineEnables multiline editing.
wrapSelects the multiline wrapping policy.
heightSets the multiline viewport height.

font

fn font(self, key: FontKey) -> Self

Selects the registered face used to shape and render editing content. Unlike Text::font, this method takes only a key; font_size configures its logical size separately. The selected registrations and font bytes must match those available to the server.

font_size

fn font_size(self, size: f32) -> Self

Sets the logical font size, initially 16. The renderer accepts finite sizes from zero through 512 logical pixels; use a positive size for ordinary editing content. Shaping validates the font configuration during evaluation. Font metrics determine single-line field height and participate in multiline reflow, caret placement, and selection geometry.

formatting

fn formatting(self, enabled: bool) -> Self

Enables persistent bold and underline spans together with Ctrl+B and Ctrl+U handling. The default is false. Formatting is represented by the editing model and participates in its undo/redo history; enabling it does not replace the model binding or make the field a different owner of the text.

width

fn width(self, width: f32) -> Self

Sets the preferred viewport width, which defaults to 240 logical pixels and must remain finite and positive. The actual region can shrink under parent constraints. This method also switches off a preceding fill_width, so the last width-policy call determines whether sizing is preferred or filling.

fill_width

fn fill_width(self) -> Self

Uses the available finite width offered by the parent. If the offer is unbounded, the configured preferred width remains the fallback. This changes width policy rather than text wrapping; multiline content still follows the separate TextWrap setting.

multi_line

fn multi_line(self) -> Self

Enables hard line breaks and multiline editing. The initial wrapping policy is TextWrap::Viewport, and the initial multiline viewport height is 120 logical pixels. The method preserves an explicitly configured wrapping policy, so .wrap(TextWrap::None).multi_line() still requests unwrapped multiline content.

wrap

fn wrap(self, wrapping: TextWrap) -> Self

Chooses how multiline content wraps independently of viewport sizing. Viewport reflows at the actual available width with room for the caret; None preserves hard breaks and allows horizontal scrolling; Fixed(width) wraps at a finite, positive text width. Calling wrap alone does not enable multiline editing.

height

fn height(self, height: f32) -> Self

Sets the multiline viewport height, initially 120 logical pixels. A multiline height must be finite and positive. Single-line fields continue to use their line height, so this setting does not turn a single-line description into a taller multiline editor.

Configuration Example

use hera_kit::{text_field, Binding, EditBuffer, TextWrap, View, ViewExt};

fn notes(document: Binding<EditBuffer>) -> impl View {
    text_field(document)
        .font_size(16.0)
        .formatting(true)
        .width(360.0)
        .fill_width()
        .multi_line()
        .wrap(TextWrap::Viewport)
        .height(200.0)
        .padding(12.0)
}

The caller owns the editing model. The field chooses its preferred fallback width before enabling fill, and it configures multiline wrapping separately from viewport height.

Retained TextField API

The retained TextField type shares font, font_size, formatting, fill_width, multi_line, wrap, and height with the behavior described above. Its width is supplied to TextField::new(runtime, state, width) or TextField::from_binding(runtime, binding, width) rather than through a width builder method. Construct that retained object once and preserve or clone it across builds so its focus, caret, and viewport storage remain stable. Its focus_target(&self) -> &FocusTarget accessor exposes the retained focus identity; it is not a view modifier.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/kit/src/text/field/mod.rs
  • crates/kit/src/input/text_input/mod.rs
  • crates/text/src/editing.rs
  • crates/text/src/lib.rs
  • crates/protocol/src/scene/primitives.rs