TextInput

TextInput is a one-line text field with a label above it and an error line below it, holding the typed text itself and passing on only valid text.

Last updated 7 November 2026

On this page

Builder
Methods
Behaviour
Test it
See also

A one-line text field with a label above it and an error line below it, like the name field of vanilla's world-creation screen.

TextInput name = TextInput.builder("name")
        .label(Text.translatable("mymod.name", "Profile name"))
        .initial(config.profileName)
        .maxLength(32)
        .validator(s -> s.trim().isEmpty() ? Text.translatable("mymod.name.empty", "Enter a name") : null)
        .onChange(s -> config.profileName = s)
        .build();

Builder#

Method	Required	Default	Notes
`label(Supplier<Text>)` / `label(Text)`	yes		the text above the field
`initial(String)`	no	`""`	the starting text, usually your current value; cut to `maxLength`; not passed to `onChange`
`maxLength(int)`	no	`64`	the most characters the field accepts; must be positive
`validator(Function<String, Text>)`	no	every text is valid	returns an error, or `null` for valid text. Runs after every edit and refresh: keep it fast.
`onChange(Consumer<String>)`	no	does nothing	receives the text after each edit that leaves it valid; main thread
`enabled`, `tooltip`, `visible`	no		options every widget has

Methods#

Method	Does
`value()`	the text in the field now, valid or not; never `null`
`isValid()`	whether the current text is valid (`error()` is `null`)
`error()`	the validator's error for the current text, or `null`
`setValue(String)`	replaces the text (cut to `maxLength`; `null` counts as empty) and calls `onChange` if it's valid. For example `setValue("")` clears the field.

Behaviour#

The typed text lives in the entry, not in your code: the field starts with initial, and a refresh doesn't reset it. That way invalid input stays while the player fixes it (State and refresh).
onChange never sees invalid text. Alternatively, an action reads value() when it runs, such as a Create button that is enabled only while name.isValid().
For numbers use a NumberField; for several lines a MultiLineInput.
Footer: yes.

Test it#

host.type("name", "");
assertTrue(host.render().contains("[input name] Profile name: \"\" (error: Enter a name)"));

See also#

Javadoc: TextInput
Validate what players type