TextBox

TextBox captures user text input for forms, search fields, and data entry with support for validation, icons, and formatting hints.

Key features:

• Visual enhancements: Add icons and text at start/end positions for context and branding
• Validation states: Built-in visual indicators for valid, warning, and error states
• Input control: Support for initial values, programmatic focus, and value setting

Often used in forms, see this guide for details.

Behaviors

This component supports the following behaviors:

Properties

autoFocus

default: false

If this property is set to true, the component gets the focus automatically when displayed.

enabled

default: true

This boolean property value indicates whether the component responds to user events (true) or not (false).

<App>
  <TextBox enabled="false" />
</App>

<App>
  <TextBox enabled="false" />
</App>

endIcon

This property sets an optional icon to appear on the end (right side when the left-to-right direction is set) of the input.

<App>
  <TextBox endIcon="email" />
</App>

<App>
  <TextBox endIcon="email" />
</App>

It is possible to set the other adornments as well: endText, startIcon and startText.

<App>
  <TextBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

<App>
  <TextBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

endText

This property sets an optional text to appear on the end (right side when the left-to-right direction is set) of the input.

<App>
  <TextBox endText=".com" />
</App>

<App>
  <TextBox endText=".com" />
</App>

It is possible to set the other adornments as well: endIcon, startIcon and startText.

<App>
  <TextBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

<App>
  <TextBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

gap

This property defines the gap between the adornments and the input area. If not set, the gap declared by the current theme is used.

initialValue

default: ""

This property sets the component's initial value.

<App>
  <TextBox initialValue="Example text" />
</App>

<App>
  <TextBox initialValue="Example text" />
</App>

invalidMessages

The invalid messages to display for the input component.

maxLength

This property sets the maximum length of the input it accepts.

Try to enter a longer value into the input field below.

<App>
  <TextBox maxLength="16" />
</App>

<App>
  <TextBox maxLength="16" />
</App>

passwordHiddenIcon

default: "eye-off"

The icon to display when the password is hidden (when showPasswordToggle is true).

passwordVisibleIcon

default: "eye"

The icon to display when the password is visible (when showPasswordToggle is true).

placeholder

An optional placeholder text that is visible in the input field when its empty.

<App>
  <TextBox placeholder="This is a placeholder" />
</App>

<App>
  <TextBox placeholder="This is a placeholder" />
</App>

readOnly

default: false

Set this property to true to disallow changing the component value.

<App>
  <TextBox initialValue="Example text" readOnly="true" />
</App>

<App>
  <TextBox initialValue="Example text" readOnly="true" />
</App>

required

default: false

Set this property to true to indicate it must have a value before submitting the containing form.

showPasswordToggle

default: false

If true, a toggle button is displayed to switch between showing and hiding the password input.

startIcon

This property sets an optional icon to appear at the start (left side when the left-to-right direction is set) of the input.

<App>
  <TextBox startIcon="hyperlink" />
</App>

<App>
  <TextBox startIcon="hyperlink" />
</App>

It is possible to set the other adornments as well: endText, startIcon and startText.

<App>
  <TextBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

<App>
  <TextBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

startText

This property sets an optional text to appear at the start (left side when the left-to-right direction is set) of the input.

<App>
  <TextBox startText="www." />
</App>

<App>
  <TextBox startText="www." />
</App>

It is possible to set the other adornments as well: endIcon, startIcon and endText.

<App>
  <TextBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

<App>
  <TextBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

validationIconError

Icon to display for error state when concise validation summary is enabled.

validationIconSuccess

Icon to display for valid state when concise validation summary is enabled.

validationStatus

default: "none"

This property allows you to set the validation status of the input component.

Available values:

<App>
  <TextBox />
  <TextBox validationStatus="valid" />
  <TextBox validationStatus="warning" />
  <TextBox validationStatus="error" />
</App>

<App>
  <TextBox />
  <TextBox validationStatus="valid" />
  <TextBox validationStatus="warning" />
  <TextBox validationStatus="error" />
</App>

verboseValidationFeedback

Enables a concise validation summary (icon) in input components.

Events

didChange

This event is triggered when value of TextBox has changed.

Signature: didChange(newValue: any): void

• newValue: The new value of the component.

Write in the input field and see how the Text underneath it is updated in parallel.

<App var.field="">
  <TextBox initialValue="{field}" onDidChange="(val) => field = val" />
  <Text value="{field}" />
</App>

<App var.field="">
  <TextBox initialValue="{field}" onDidChange="(val) => field = val" />
  <Text value="{field}" />
</App>

gotFocus

This event is triggered when the TextBox has received the focus.

Signature: gotFocus(): void

Clicking on the TextBox in the example demo changes the label text. Note how clicking elsewhere resets the text to its original.

<App>
  <TextBox
    initialValue="{focused === true ? 'I got focused!' : 'I lost focus...'}"
    onGotFocus="focused = true"
    onLostFocus="focused = false"
    var.focused="{false}"
  />
</App>

<App>
  <TextBox
    initialValue="{focused === true ? 'I got focused!' : 'I lost focus...'}"
    onGotFocus="focused = true"
    onLostFocus="focused = false"
    var.focused="{false}"
  />
</App>

lostFocus

This event is triggered when the TextBox has lost the focus.

Signature: lostFocus(): void

Exposed Methods

focus

This method sets the focus on the TextBox component.

Signature: focus(): void

<App>
  <Button label="Trigger Focus" onClick="inputComponent.focus()" />
  <TextBox id="inputComponent" />
</App>

<App>
  <Button label="Trigger Focus" onClick="inputComponent.focus()" />
  <TextBox id="inputComponent" />
</App>

setValue

This API sets the value of the TextBox. You can use it to programmatically change the value.

Signature: setValue(value: string): void

• value: The new value to set. If the value is empty, it will clear the input.

<App var.changes="">
  <TextBox
    id="inputField"
    readOnly="true"
    onDidChange="changes++"
  />
  <HStack>
    <Button
      label="Check"
      onClick="inputField.setValue('example ')"
    />
    <Text value="Number of changes: {changes}" />
  </HStack>
</App>

<App var.changes="">
  <TextBox
    id="inputField"
    readOnly="true"
    onDidChange="changes++"
  />
  <HStack>
    <Button
      label="Check"
      onClick="inputField.setValue('example ')"
    />
    <Text value="Number of changes: {changes}" />
  </HStack>
</App>

value

You can query the component's value. If no value is set, it will retrieve undefined.

Signature: get value(): string | undefined

In the example below, typing in the TextBox will also display the length of the text typed into it above the field:

<App>
  <Text value="TextBox content length: {inputComponent.value.length}" />
  <TextBox id="inputComponent" />
</App>

<App>
  <Text value="TextBox content length: {inputComponent.value.length}" />
  <TextBox id="inputComponent" />
</App>

Parts

The component has some parts that can be styled through layout properties and theme variables separately:

• endAdornment: The adornment displayed at the end of the text box.
• input: The text box input area.
• label: The label displayed for the text box.
• startAdornment: The adornment displayed at the start of the text box.

Default part: input

Styling

Theme Variables