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.
| Method | Purpose |
|---|---|
font | Selects the registered editing font. |
font_size | Sets the logical font size. |
formatting | Enables persistent rich-text formatting. |
width | Sets a preferred viewport width. |
fill_width | Uses the finite offered viewport width. |
multi_line | Enables multiline editing. |
wrap | Selects the multiline wrapping policy. |
height | Sets the multiline viewport height. |
font
fn font(self, key: FontKey) -> SelfSelects 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) -> SelfSets 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) -> SelfEnables 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) -> SelfSets 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) -> SelfUses 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) -> SelfEnables 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) -> SelfChooses 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) -> SelfSets 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.rscrates/kit/src/input/text_input/mod.rscrates/text/src/editing.rscrates/text/src/lib.rscrates/protocol/src/scene/primitives.rs