TextBox

The TextBox is an input component that allows users to input and edit textual data.

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>

endIcon

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

<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>

endText

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

<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>

initialValue

This property sets the component's initial value.

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

label

This property sets the label of the component.

labelBreak (default: false)

This boolean value indicates if the TextBox labels 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:

labelWidth

This property sets the width of the TextBox.

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>

placeholder

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

<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>

required

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

startIcon

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

<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>

startText

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

<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>

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>

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>

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>

lostFocus

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

Exposed Methods

focus

This method sets the focus on the TextBox.

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

setValue

You can use this method to set the component's current value programmatically (true: checked, false: unchecked).

<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.

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>

Styling

The TextBox component uses these theme variables:

These variables have 4 variants depending on the validationStatus denoted by |status|. If the status segment is omitted, the style will be applied to all validation statuses.

• borderRadius-TextBox-|status|
• borderWidth-TextBox-|status|
• borderStyle-TextBox-|status|
• fontSize-TextBox-|status|
• color-placeholder-TextBox-|status|

"borderRadius-TextBox-default": "10px",
"color-placeholder-TextBox-error": "crimson"

In addition to the validation statuses, the variables below are associated with styles for hover and focus interaction states denoted by |interact| in their signature:

• borderColor-TextBox-|status|--|interact|
• backgroundColor-TextBox-|status|--|interact|
• boxShadow-TextBox-|status|--|interact|
• textColor-TextBox-|status|--|interact|

"backgroundColor-TextBox-default--hover": "gray",
"textColor-TextBox-error--focus": "lightcoral"

The following variables are only used in the focus state:

• outlineWidth-TextBox-|status|--focus
• outlineColor-TextBox-|status|--focus
• outlineStyle-TextBox-|status|--focus
• outlineOffset-TextBox-|status|--focus

These variables set the disabled state:

• backgroundColor-TextBox--disabled
• textColor-TextBox--disabled
• borderColor-TextBox--disabled

Example

"borderRadius-TextBox": "30px",
"color-placeholder-TextBox-default": "blue"

To style all input controls not just this component, replace the TextBox segment with Input:

borderColor-Input: "#0033FF"

Input affects the following controls:

• Checkbox
• NumberBox
• RadioGroupOption
• Select
• Switch
• TextArea
• MultiSelect
• MultiCombobox

See custom themes for styling details.

Theme Variables