Logo

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.

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>
Example: enabled
<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>
Example: endIcon
<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>
Example: all adornments
<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>
Example: endText
<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>
Example: all adornments
<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>
Example: initialValue
<App>
  <TextBox initialValue="Example text" />
</App>

label

This property sets the label of the component. If not set, the component will not display a label.

labelBreak (default: true)

This boolean value indicates whether the TextBox label can be split into multiple lines if it would overflow the available label width.

labelPosition (default: "top")

Places the label at the given position of the component.
Available values:
ValueDescription
startThe left side of the input (left-to-right) or the right side of the input (right-to-left)
endThe right side of the input (left-to-right) or the left side of the input (right-to-left)
topThe top of the input (default)
bottomThe bottom of the input

labelWidth

This property sets the width of the TextBox component's label. If not defined, the label's width will be determined by its content and the available space.

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>
Example: maxLength
<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>
Example: placeholder
<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>
Example: readOnly
<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>
Example: startIcon
<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>
Example: all adornments
<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>
Example: startText
<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>
Example: all adornments
<App>
  <TextBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

validationStatus (default: "none")

This property allows you to set the validation status of the input component.
Available values:
ValueDescription
validVisual indicator for an input that is accepted
warningVisual indicator for an input that produced a warning
errorVisual indicator for an input that produced an error
<App>
  <TextBox />
  <TextBox validationStatus="valid" />
  <TextBox validationStatus="warning" />
  <TextBox validationStatus="error" />
</App>
Example: validationStatus
<App>
  <TextBox />
  <TextBox validationStatus="valid" />
  <TextBox validationStatus="warning" />
  <TextBox validationStatus="error" />
</App>

Events

didChange

This event is triggered when value of TextBox has changed.
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>
Example: didChange
<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.
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>
Example: gotFocus/lostFocus
<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.

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>
Example: focus
<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>
Example: setValue
<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>
Example: value
<App>
  <Text value="TextBox content length: {inputComponent.value.length}" />
  <TextBox id="inputComponent" />
</App>

Styling

Theme Variables

VariableDefault Value (Light)Default Value (Dark)
backgroundColor-Input--disabled$backgroundColor--disabled$backgroundColor--disabled
backgroundColor-TextBox--disablednonenone
backgroundColor-TextBox-defaultnonenone
backgroundColor-TextBox-default--focusnonenone
backgroundColor-TextBox-default--hovernonenone
backgroundColor-TextBox-errornonenone
backgroundColor-TextBox-error--focusnonenone
backgroundColor-TextBox-error--hovernonenone
backgroundColor-TextBox-successnonenone
backgroundColor-TextBox-success--focusnonenone
backgroundColor-TextBox-success--hovernonenone
backgroundColor-TextBox-warningnonenone
backgroundColor-TextBox-warning--focusnonenone
backgroundColor-TextBox-warning--hovernonenone
borderColor-Input--disabled$borderColor--disabled$borderColor--disabled
borderColor-Input-error$borderColor-Input-default--error$borderColor-Input-default--error
borderColor-Input-success$borderColor-Input-default--success$borderColor-Input-default--success
borderColor-Input-warning$borderColor-Input-default--warning$borderColor-Input-default--warning
borderColor-TextBox--disablednonenone
borderColor-TextBox-defaultnonenone
borderColor-TextBox-default--focusnonenone
borderColor-TextBox-default--hovernonenone
borderColor-TextBox-errornonenone
borderColor-TextBox-error--focusnonenone
borderColor-TextBox-error--hovernonenone
borderColor-TextBox-successnonenone
borderColor-TextBox-success--focusnonenone
borderColor-TextBox-success--hovernonenone
borderColor-TextBox-warningnonenone
borderColor-TextBox-warning--focusnonenone
borderColor-TextBox-warning--hovernonenone
borderRadius-Input$borderRadius$borderRadius
borderRadius-TextBox-defaultnonenone
borderRadius-TextBox-errornonenone
borderRadius-TextBox-successnonenone
borderRadius-TextBox-warningnonenone
borderStyle-Inputsolidsolid
borderStyle-TextBox-defaultnonenone
borderStyle-TextBox-errornonenone
borderStyle-TextBox-successnonenone
borderStyle-TextBox-warningnonenone
borderWidth-Input1px1px
borderWidth-TextBox-defaultnonenone
borderWidth-TextBox-errornonenone
borderWidth-TextBox-successnonenone
borderWidth-TextBox-warningnonenone
boxShadow-TextBox-defaultnonenone
boxShadow-TextBox-default--focusnonenone
boxShadow-TextBox-default--hovernonenone
boxShadow-TextBox-errornonenone
boxShadow-TextBox-error--focusnonenone
boxShadow-TextBox-error--hovernonenone
boxShadow-TextBox-successnonenone
boxShadow-TextBox-success--focusnonenone
boxShadow-TextBox-success--hovernonenone
boxShadow-TextBox-warningnonenone
boxShadow-TextBox-warning--focusnonenone
boxShadow-TextBox-warning--hovernonenone
color-adornment-Input$textColor-subtitle$textColor-subtitle
color-adornment-TextBox-defaultnonenone
color-adornment-TextBox-errornonenone
color-adornment-TextBox-successnonenone
color-adornment-TextBox-warningnonenone
color-passwordToggle-Input$textColor-subtitle$textColor-subtitle
color-passwordToggle-TextBoxnonenone
color-passwordToggle-TextBox--focusnonenone
color-passwordToggle-TextBox--hovernonenone
fontSize-placeholder-TextBox-defaultnonenone
fontSize-placeholder-TextBox-errornonenone
fontSize-placeholder-TextBox-successnonenone
fontSize-placeholder-TextBox-warningnonenone
fontSize-TextBox-defaultnonenone
fontSize-TextBox-errornonenone
fontSize-TextBox-successnonenone
fontSize-TextBox-warningnonenone
gap-adornment-Input$space-2$space-2
gap-adornment-TextBoxnonenone
minHeight-Input39px39px
outlineColor-Input--focus$outlineColor--focus$outlineColor--focus
outlineColor-TextBox-default--focusnonenone
outlineColor-TextBox-error--focusnonenone
outlineColor-TextBox-success--focusnonenone
outlineColor-TextBox-warning--focusnonenone
outlineOffset-Input--focus$outlineOffset--focus$outlineOffset--focus
outlineOffset-TextBox-default--focusnonenone
outlineOffset-TextBox-error--focusnonenone
outlineOffset-TextBox-success--focusnonenone
outlineOffset-TextBox-warning--focusnonenone
outlineStyle-Input--focus$outlineStyle--focus$outlineStyle--focus
outlineStyle-TextBox-default--focusnonenone
outlineStyle-TextBox-error--focusnonenone
outlineStyle-TextBox-success--focusnonenone
outlineStyle-TextBox-warning--focusnonenone
outlineWidth-Input--focus$outlineWidth--focus$outlineWidth--focus
outlineWidth-TextBox-default--focusnonenone
outlineWidth-TextBox-error--focusnonenone
outlineWidth-TextBox-success--focusnonenone
outlineWidth-TextBox-warning--focusnonenone
padding-Input$space-2$space-2
padding-TextBox-defaultnonenone
padding-TextBox-errornonenone
padding-TextBox-successnonenone
padding-TextBox-warningnonenone
paddingLeft-passwordToggle-TextBoxnonenone
paddingRight-passwordToggle-TextBoxnonenone
textColor-Input$textColor-primary$textColor-primary
textColor-Input--disabled$textColor--disabled$textColor--disabled
textColor-placeholder-Input$textColor-subtitle$textColor-subtitle
textColor-placeholder-TextBox-defaultnonenone
textColor-placeholder-TextBox-errornonenone
textColor-placeholder-TextBox-successnonenone
textColor-placeholder-TextBox-warningnonenone
textColor-TextBox--disablednonenone
textColor-TextBox-defaultnonenone
textColor-TextBox-default--focusnonenone
textColor-TextBox-default--hovernonenone
textColor-TextBox-errornonenone
textColor-TextBox-error--focusnonenone
textColor-TextBox-error--hovernonenone
textColor-TextBox-successnonenone
textColor-TextBox-success--focusnonenone
textColor-TextBox-success--hovernonenone
textColor-TextBox-warningnonenone
textColor-TextBox-warning--focusnonenone
textColor-TextBox-warning--hovernonenone
This site is an XMLUI™ app.