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>

type

default: "text"

Sets the HTML input type. Use "password" to hide the entered text and classify the value as a secret in the audit pipeline; "email" to classify the value as sensitive (PII).

Available values: text (default), password, search, email

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