Skip to main content

Input

This page describes how to use an Input widget to gather and validate user input such as text, numbers, emails, and passwords.

How to use Input Widget

Data validation

Input widgets gather user-provided data, which can be accessed using the widget's text property. First, however, it's important to help users provide clean and well-formatted data.

Properties under the "Validation" tab in the properties pane can be configured to enforce specific rules on what the user has entered.

When any of the validation rules have been broken, the widget flags itself as invalid; the border shows red, and its Error Message appears. If the widget is part of a Form widget, that Form (by default) can't be submitted while it contains invalid data.

Regex

The Regex property is used to compare input to a regular expression that you have defined. If the user's input doesn't match the pattern, it's considered invalid.

This is useful when you need to guarantee that the content exactly follows the formatting of your dataset.

For example, if you'd like to create an input for a person's name, you can add the following regular expression to restrict input to only alphabetical characters, spaces, and certain special characters:

/^[a-z ,.'-]+$/i

Valid

In the Valid property field, you can write a code expression to evaluate the user's input. Or, if you have more complex logic, you can define a function in a JS Object to determine whether it's acceptable. The input is acceptable when the Valid field evaluates to true.

Use this property when you have rules or logic beyond simple formatting that the input must follow.

As an example, imagine that you are creating rules for a "Create Password" field in an account registration form. If you want to be sure that new passwords don't contain certain strings, you may write:

// Valid property of an Input widget
{{
!["password", "123", "admin"].some(subStr => {
return PasswordInput.text.toLowerCase().includes(subStr)
})
}}

Other validation properties include:

  • Required: Makes the input mandatory. When the field is left blank, it's considered invalid.
  • Max Characters: Limits the number of characters that the input allows.
  • Min / Max: Input less than Min or greater than Max is invalid.

To see some of these validations in practice, visit the sample app.

Properties

Properties allow you to edit the table, connect it with other widgets, and customize how the user interacts with it.

General properties

General properties control the data and behavior of the Input widget. These properties are present in the widget's properties pane.

PropertyDescription
Data TypeSets the type of data you want to capture in the user input. Selecting a data type adds the associated validation to the user input. Choose from Single-line text, Multi-line text, Number, Password, or Email.
Default valueSets the widget's default value before the user has made any changes.
TextSets the label text of the widget.
PositionSets where the label appears relative to the widget's input area. Choose between Left, Top, or Auto.
RequiredSets whether the input field is a mandatory field. When this is turned on and the user has left the field blank, it's considered invalid.
Max CharactersSets a maximum length allowed for user input. Only appears when Data Type is set to a Text type.
MinSets a minimum value allowed for user input. Only appears when Data Type is set to Number.
MaxSets a maximum value allowed for user input. Only appears when Data Type is set to Number.
RegexUsed to add custom regex validation to perform on user input. When the input doesn't match the regex expression, the input is considered invalid.
ValidSets an expression to decide whether the user's input is considered valid. When the expression evaluates to false, the input is considered invalid.
Error messageSets the text of the error message to display if user input is invalid.
SpellcheckWhen enabled, user input is checked for spelling errors. This doesn't affect whether the input is considered invalid.
TooltipSets a tooltip for the widget on mouse hover. You can add hints or extra information about the required input.
PlaceholderSets the placeholder text within the input box. Use to show a hint or example value to the user.
Show step arrowsControls visibility of step arrows. Turning this toggle off hides the step arrows to increment or decrement the values in the widget. Only appears when Data Type is set to Number.
VisibleControls widget's visibility on the page. When turned off, the widget isn't visible when the app is published. It appears translucent when in Edit mode.
DisabledMakes the widget un-clickable or unusable. The widget remains visible to the user, but user interaction isn't allowed.
Animate LoadingWhen turned off, the widget loads without any skeletal animation.
AutofocusWhen enabled, the user's cursor focuses on the input box automatically on page load.
HeightConfigures how a widget’s height reacts to content changes. It has three possible configurations:
Fixed: The height of the widget remains as set using drag and resize.
Auto Height: The height of the widget reacts to content changes.
Auto Height with limits: Same as Auto height, with a configurable option to set the minimum and maximum number of rows that can be occupied by the widget.
Reset on SubmitClears the value entered by the user after the user submits with the Enter key.

Reference properties

Reference properties are used to access the widget's data and state using code. When using reference properties, substitute <input_name> in the examples below with the name of your Input widget.

PropertyDescriptionCode Snippet
textContains the widget's text / user input, either as a string or number. depending on the widget's Data Type property.{{ Input1.text }}
isDisabledReflects the state of the widget's Disabled setting.{{ Input1.isDisabled }}
isValidReflects whether the widget's input is considered Valid.{{ Input1.isValid }}
isVisibleReflects the state of the widget's Visible setting.{{ Input1.isVisible }}

Style properties

Style properties allow you to change the look and feel of the Input widget. These properties are present in the widget's properties pane.

PropertyDescription
IconSets an icon to be included on the button. Uses icons from the Blueprint library. See the list of icons here.
PositionSets whether the icon appears on the left or right of the button's label text.
Font ColorSets the text color for the label. Accepts valid CSS color values.
Font SizeSets the size of the label font. Accepts valid CSS font-size values.
EmphasisToggles font styles (bold or italic).
Border RadiusRounds the corners of the widget's outer edge. With JS enabled, this accepts valid CSS border-radius values.
Box ShadowCasts a drop shadow from the frame of the widget. With JS enabled, this accepts valid CSS box-shadow values.

Events

These event handlers can be used to run queries, JS code, or other supported actions when the event is triggered.

EventDescription
onTextChangedSets an action to take place when the input's value is changed.
onFocusSets an action to take place when the widget has focus (when the user's text cursor is in the field).
onBlurSets an action to take place when the input loses focus.
onSubmitSets an action to take place when the input is submitted with the Enter key. When the widget's Data Type is set to Multi-line text, the submit is triggered by CTRL + Enter instead.

Further reading