Documentation menu

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.

MethodPurpose
fontSelects a registered face and logical size.
ui_fontSelects the bundled UI face and fallback policy.
font_weightRequests a registered weight variant.
boldRequests the bold weight variant.
underlineControls underline decoration.
directionSets the paragraph’s base direction.
alignmentAligns shaped lines horizontally.
single_lineSelects single-line shaping.
multi_lineAllows line breaks and wrapping.
max_linesLimits the emitted multiline content.
max_widthSets a wrapping and alignment width.

font

fn font(self, font_key: FontKey, size: f32) -> Self

Selects 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) -> Self

Selects 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) -> Self

Requests 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) -> Self

Requests 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) -> Self

Enables 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) -> Self

Sets 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) -> Self

Places 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) -> Self

Selects 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) -> Self

Allows 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) -> Self

Selects 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) -> Self

Sets 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.rs
  • crates/font/src/registry.rs
  • crates/text/src/shaping.rs
  • crates/text/src/lib.rs
  • crates/font/src/lib.rs
  • crates/protocol/src/scene/primitives.rs