Skip to content

TextField

TextField is a text box. Its outline shows when it has focus. It can have a label and helper text, and it can check what the user types. It can also be a multiline editor.

Usage

Call Components.TextField with a scope and a table of properties:

C.TextField(scope, {
    Label = "Email",
    Placeholder = "you@example.com",
    Helper = "We never share it.",
    Validators = { V.required(), V.email() }, -- (1)!
    OnChanged = function(text)
        print("Typed", text)
    end,
})
  1. V is Pantheon.Validators. The validators run when the field loses focus. If one fails, its message replaces the helper text. If several fail, the first one shows. See Validators.

Properties

Name Type Required Default Description
Theme ThemeRef ❌ The contextual theme Theme to use for this component instead of the one from Theme.Provide.
LayoutOrder UsedAs<number> ❌ 0 Position in a parent UIListLayout or UIGridLayout.
Size UsedAs<UDim2> ❌ - Size of the component.
Visible UsedAs<boolean> ❌ true Whether the component is shown.
Text UsedAs<string> ❌ "" The text. A plain string is only the starting text. A Value stays in step with the box: it changes as the user types, and setting it changes the box.
Placeholder UsedAs<string> ❌ "" Text to show while the box is empty.
Label UsedAs<string> ❌ - Small label above the box.
Helper UsedAs<string> ❌ - Hint under the box. An error replaces it.
Error UsedAs<string> ❌ - Error message to show. It overrides the result of Validators.
Multiline boolean ❌ false Allow several lines of text.
MinLines number ❌ 1, or 3 when multiline Height of the box, in lines, when it is empty.
MaxLines number ❌ 1, or 12 when multiline Greatest height, in lines, that the box grows to.
Resize TextFieldResize ❌ "None", or "Y" when multiline Which directions the handle in the corner can resize.
Disabled UsedAs<boolean> ❌ false Stops the user editing the box. The component reads this once, when it creates the field.
LeadingIcon string ❌ - Lucide icon at the start of the box.
TrailingIcon string ❌ - Lucide icon at the end of the box.
Validators { Validator } ❌ - Validators to run on the text. The component checks them in order.
ValidateOnBlur boolean ❌ true Run the validators when the box loses focus. Set it to false to use Error only.
Compact boolean ❌ false A smaller version for fields inside other widgets. It is 28 pixels tall, with less padding and 13-pixel text.
Height number ❌ 40, or 28 when compact Height of the box, in pixels.
Prefix string ❌ - Fixed text at the start of the box, such as "#".
Id string ❌ - Key that identifies this component when state is kept across rebuilds. See Persist.

Callbacks

Name Description
OnChanged: (string) -> () Runs with the text each time it changes.
OnSubmit: (text: string, box: TextBox) -> () Runs with the text and the TextBox when the user presses Enter or clicks away. Use it to confirm the value or to restore the old text.

See also