text
Shape, measure, and describe text as retained glyph runs with consistent font registration.
Use text(value) -> Text for a string that should participate in layout with its actual font metrics and line breaks. The view owns the string and shaping configuration, allowing Kit to measure the content in the application process and send positioned glyph runs to Hera for rendering.
Typography
use hera_kit::{Color, ViewExt, text};
let title = text("Your library")
.ui_font(28.0)
.bold()
.single_line()
.foreground(Color::rgba(0.12, 0.14, 0.18, 1.0));The example uses the toolkit's UI face; select another registered face explicitly with .font(FontKey, size). Within a registered family, .font_weight requests a weight and .bold() supplies the bold convenience form. You can also add underline decoration with .underline(true). Set these text-specific options before common wrappers such as foreground and padding.
Line Layout and Direction
Line policy determines how the shaped text responds to available space. Choose .single_line() or .multi_line(), then use .max_width(width) and .max_lines(count) when the design needs additional bounds. Direction and line placement can be configured independently through .direction(TextDirection) and .alignment(TextAlignment).
Text also responds to its actual layout proposal. A configured maximum width is not permission to ignore a smaller finite parent constraint.
Font Asset Consistency
The positioned glyphs refer to the exact face that the client used for shaping. To render the intended outlines, the daemon must therefore share the client's font registrations and bytes. Keys 0 and 1 identify the configured default and embedded Inter regular respectively; other keys must agree across the participating processes.
To provide weight variants, register faces with their regular family's key and a weight from 100 through 900 in steps of 100. A weight request selects the nearest registered face in that family, falling back to the original face when necessary. This preserves real glyph outlines and metrics rather than synthesizing bold outlines.
Store app-owned font files and licenses in apps/<app>/assets/. Manifest paths are relative to the manifest location, so deployment must preserve that layout.
Text Editing
When the user needs to change the string, use text_field to add selection, caret movement, composition, and undo behavior around an editing model. The text internals guide explains the shaping and GPU atlas work shared by display text and editing controls.
Component-Specific Reference
The following methods configure Text and return Self. Their shaping and layout settings remain part of the view description, so apply them before common modifiers such as foreground or padding return a wrapper.
| Method | Purpose |
|---|---|
font | Selects a registered face and logical size. |
ui_font | Selects the bundled UI face and fallback policy. |
font_weight | Requests a registered weight variant. |
bold | Requests the bold weight variant. |
underline | Controls underline decoration. |
direction | Sets the paragraph’s base direction. |
alignment | Aligns shaped lines horizontally. |
single_line | Selects single-line shaping. |
multi_line | Allows line breaks and wrapping. |
max_lines | Limits the emitted multiline content. |
max_width | Sets a wrapping and alignment width. |
font
fn font(self, font_key: FontKey, size: f32) -> SelfSelects a registered font key and logical font size. The renderer accepts finite sizes from zero through 512 logical pixels; use a positive size for ordinary visible text. A new text view uses key zero at size 16. Calling font switches off the UI-face selection enabled by ui_font; a later call replaces the key and size. Unknown fonts and invalid shaping configuration fail during evaluation.
ui_font
fn ui_font(self, size: f32) -> SelfSelects the bundled UI face at the requested logical size, subject to the same size limits as font. Missing scripts use the toolkit’s whole-block fallback policy, and the resolved font key is shared by measurement and server rendering. Calling ui_font after font restores UI-face selection.
font_weight
fn font_weight(self, weight: FontWeight) -> SelfRequests a weight variant within the selected font family. The default is FontWeight::Normal; the enum also includes Thin, ExtraLight, Light, Medium, SemiBold, Bold, ExtraBold, and Black. Selection uses registered faces and their real metrics rather than synthesizing a heavier outline.
bold
fn bold(self) -> SelfRequests FontWeight::Bold as a convenience for font_weight. A later font_weight call can choose another variant, including Normal. This affects the selected face and its metrics rather than adding a separate compositing effect.
underline
fn underline(self, enabled: bool) -> SelfEnables or disables underline decoration, which is initially disabled. The underline uses shaped text geometry, font metrics, and the inherited foreground paint. Passing false removes the decoration from the next description without changing the string.
direction
fn direction(self, direction: TextDirection) -> SelfSets the paragraph base direction to Auto, LeftToRight, or RightToLeft. The default, Auto, infers direction from the paragraph and falls back to left-to-right. This controls bidirectional ordering independently of line alignment; it does not reverse the order of children in a surrounding stack.
alignment
fn alignment(self, alignment: TextAlignment) -> SelfPlaces shaped lines within the available text width using Left, Center, Right, Start, or End. The default is Left. Start and End follow each paragraph’s resolved direction, while the other variants use physical positions. This aligns text lines rather than positioning the Text view within its parent.
single_line
fn single_line(self) -> SelfSelects single-line shaping, the default mode. Use it for labels whose content should remain on one line rather than wrapping into a paragraph. It changes the text mode without imposing a fixed surrounding frame or adding an ellipsis.
multi_line
fn multi_line(self) -> SelfAllows explicit line breaks and wrapping under the configured and offered widths. The text’s measured height follows the resulting lines, subject to a configured line limit. This controls display text; it does not create an editable multiline field.
max_lines
fn max_lines(self, lines: usize) -> SelfSelects multiline mode and limits how many wrapped or explicit lines are emitted. The count must be positive; zero fails text validation. The default line limit is absent, allowing all lines. Content beyond the limit is omitted without an ellipsis. Because this method changes the mode, its position relative to a later single_line call matters.
max_width
fn max_width(self, width: f32) -> SelfSets the wrapping and alignment width, which is initially unspecified. The value must be finite and positive. Layout still accounts for a smaller finite parent proposal, so this value does not reserve an unconditional width or override the surrounding container’s constraints.
Configuration Example
use hera_kit::{text, FontWeight, TextAlignment, TextDirection, ViewExt};
let paragraph = text("A reusable description of the current interface.")
.ui_font(18.0)
.font_weight(FontWeight::Medium)
.underline(true)
.direction(TextDirection::Auto)
.alignment(TextAlignment::Start)
.multi_line()
.max_width(320.0)
.max_lines(3)
.padding(12.0);The text-specific calls configure shaping before padding wraps the completed description. The line limit does not add a truncation indicator.
Runtime Attribute Access
Text::new(value) is the associated constructor used to create the same kind of description as text(value). The separate text_attr(&self, runtime: &mut Runtime) -> AttrId method opts into a runtime-owned string attribute for dynamic updates; it is not a consuming view modifier. Its ID remains valid after that Text description is dropped, following runtime state lifetime rather than ordinary mounted ownership. Keep that access in code that owns the runtime and use normal props or bindings for reusable application composition.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/kit/src/text/mod.rscrates/font/src/registry.rscrates/text/src/shaping.rscrates/text/src/lib.rscrates/font/src/lib.rscrates/protocol/src/scene/primitives.rs