Text Input

TextInput widget

The TextInput Widget enables the rendering of interactive text input fields, allowing users to enter and edit text within your application for data input and interaction.

Test in Kitchen Sink (opens in a new tab)

Properties

PropertyTypeDescription
idstringID to be referenced later
maxWidthintegerThe max width of this Input widget (default 700). while min vlaue can be 0 and maximum can be 5000
labelstringLabel for your widget
labelHintstringHint text on your label
labelStyleTextStyleStyling for the label
hintTextstringHint text explaining your widget
hintStyleobjectStyling the hint text. Default to theme's bodyMedium styling. see properties
requiredbooleanWhether the field is required
enabledbooleanEnables or disables the interactivity and input functionality of the widget
iconobjectSee properties
stylesobjectSee properties
validatorobjectSee properties Example (opens in a new tab)
validateOnUserInteractionbooleanDefault: false. When set to true, validates the user's input on every keypress. Example (opens in a new tab)
valuestringSpecifying the value of your Text Input
inputTypestringPick a predefined input type default email phone number text url datetime ipAddress
keyboardActionstringSpecify the action key on native device's soft keyboard
obscureTextbooleanwhether we should obscure the typed-in text (e.g Social Security)
obscureTogglebooleanenable the toggling between plain and obscure text.
readOnlybooleanWhen it is true, the text cannot be modified by any shortcut or keyboard operation.
selectablebooleanSetting this to true will enable features such as long-pressing the TextField to select text and show the cut/copy/paste menu, and tapping to move the text caret text.
toolbarDonebooleanDisplay the toolbar with done button on top of the keyboard. (defaults to False)
textStyleobjectAn opaque object that determines the size, color, and decoration of text. Similar properties as hintStyle see properties
maskstringIt formats the input by a given mask. Ex: +# (###) ###-##-##. detailed examples can be seen in Kitchen Sink (opens in a new tab)
delayedKeyPressDurationintegerThe delay in milliseconds to trigger onDelayedKeyPress ( min : 0)
multilinebooleanSpecifies if this TextInput can span multiple lines. (default False)
minLinesintegerSpecifies the minimum number of lines to start out (applicable for multiline)
maxLinesintegerSpecifies the maximum number of lines to visually expand to. This will also enable multi-line if this number is greater than 1 and the 'multiline' property is not set.
floatLabelbooleanfloating label example
autofillHintsarrayList of autofill hints used to specify what type of information should be autofilled. Possible values: "addressCity", "addressCityAndState", "addressState", "birthday", "birthdayDay", "birthdayMonth", "birthdayYear", "countryCode", "countryName", "creditCardExpirationDate", "creditCardExpirationDay", "creditCardExpirationMonth", "creditCardExpirationYear", "creditCardFamilyName", "creditCardGivenName", "creditCardMiddleName", "creditCardName", "creditCardNumber", "creditCardSecurityCode", "creditCardType", "email", "familyName", "fullStreetAddress", "gender", "givenName", "impp", "jobTitle", "language", "location", "middleInitial", "middleName", "name", "namePrefix", "nameSuffix", "newPassword", "newUsername", "nickname", "oneTimeCode", "organizationName", "password", "photo", "postalAddress", "postalAddressExtended", "postalAddressExtendedPostalCode", "postalCode", "streetAddressLevel1", "streetAddressLevel2", "streetAddressLevel3", "streetAddressLevel4", "streetAddressLine1", "streetAddressLine2", "streetAddressLine3", "sublocality", "telephoneNumber", "telephoneNumberAreaCode", "telephoneNumberCountryCode", "telephoneNumberDevice", "telephoneNumberExtension", "telephoneNumberLocal", "telephoneNumberLocalPrefix", "telephoneNumberLocalSuffix", "telephoneNumberNational", "transactionAmount", "transactionCurrency", "url", "username"
maxLengthintegerThe maximum number of characters allowed in the text field. If set, the text field will restrict the input to this number of characters.
maxLengthEnforcementstringnone, enforced, truncateAfterCompositionEnds. see properties

Actions

Namedescription
onKeyPressOn every keystroke, call Ensemble's built-in functions or execute code
onFocusReceivedExecute an Ensemble action when the field receives focus
onFocusLostExecute an Ensemble action when the field loses focus
onChangeCall Ensemble's built-in functions or execute code when the input changes. This event only dispatches if the text changes AND the focus is lost (e.g. clicking on button)
onDelayedKeyPressExecute an Action after a brief delay specified by delayedKeyPressDuration (default: 300 ms). Consecutive calls within this delay will reset the timer, useful for minimizing server calls for type-ahead scenarios.

icon

PropertyTypeDescription
namestringThe name of the icon
librarystringWhich icon library to use.
colorinteger or stringThe color specification for the text, which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
sizeintegerDefines the dimensions or magnitude of an element, allowing control over its overall size within the layout.

styles

PropertyTypeDescription
fontSizeintegerSets the size of the text.
borderRadiusstring or integerThe border radius of the widget.This can be specified using CSS-like notation with 1 to 4 integers. Minimum value: 0.
borderColorinteger or stringSets the border color, starting with '0xFF' for full opacity. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
borderWidthintegerThickness of the border. Minimum value should be 0.
fontSizeintegerSets the size of the text.
stackPositionTopintegerThe distance of the child's top edge from the top of the stack. This is applicable only for Stack's children.
stackPositionBottomintegerThe distance that the child's bottom edge from the bottom of the stack. This is applicable only for Stack's children.
stackPositionLeftintegerThe distance that the child's left edge from the left of the stack. This is applicable only for Stack's children.
stackPositionRightintegerThe distance that the child's right edge from the right of the stack. This is applicable only for Stack's children.
errorBorderColorinteger or stringThe border color when there are errors on this input field. This property can be defined in the theme to apply to all Input widgets, starting with '0xFF' for full opacity. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
focusedBorderColorinteger or stringThe border color when this input field is receiving focus. This property can be defined in the theme to apply to all Input widgets, starting with '0xFF' for full opacity. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
focusedErrorBorderColorinteger or stringThe border color of this input field when it is receiving focus in its error state. This property can be defined in the theme to apply to all Input widgets, starting with '0xFF' for full opacity. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
disabledBorderColorinteger or stringThe border color when this input field is disabled. This property can be defined in the theme to apply to all Input widgets, starting with '0xFF' for full opacity. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
fillColorinteger or stringThe fill color for this input fields. This property can be defined in the theme to apply to all Input widgets, starting with '0xFF' for full opacity. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
contentPaddinginteger or stringPadding around your input content with CSS-style notation e.g. margin: 5 20 5
variantstringSelect a pre-defined look and feel for this Input widget. This property can be defined in the theme to apply to all Input widgets. see properties
alignmentstringThe alignment of the widget relative to its parent. topLeft, topCenter, topRight, centerLeft, center, centerRight, bottomLeft, bottomCenter, bottomRight
visiblebooleanToggle a widget visibility on/off. Note that an invisible widget will not occupy UI space, unless the visibilityTransitionDuration is specified.
visibilityTransitionDurationnumberSpecify the duration in seconds when a widget animates between visible and not visible state. Note that setting this value will cause the widget to still occupy the UI space even when it is not visible.
captureWebPointerbooleanApplicable for Web only. When overlaying widgets on top of certain HTML container (e.g. Maps), the mouse click is captured by the HTML container, causing issue interacting with the widget. Use this to capture and maintain the mouse pointer on your widget.
expandedbooleanIf the parent is a Row or Column, this flag will stretch this widget in the appropriate direction. (e.g stretch horizontally for parent of type Row)
elevationintegerThe z-coordinate at which to place this material relative to its parent. A non-zero value will show a shadow, with its size relative to the elevation value. Minimum value: 0, Maximum value: 24
elevationShadowColorinteger or stringThe shadow color for the elevation, which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
elevationBorderRadiusstring or integerThe border radius of the widget.This can be specified using CSS-like notation with 1 to 4 integers. Minimum value: 0.

hintStyles

PropertyTypeDescription
fontSizeintegerSets the size of the text.
fontWeightstringThe thickness of the glyphs used to draw the text. light normal bold w100 w200 w300 w400 w500 w600 w700 w800``w900
colorinteger or stringThe color specification for the text, icons, divider etc, which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
overflowstringSet treatment of text longer than available space wrap visible clip ellipsis
backgroundColorinteger or stringBackground color of the box. which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
fontfamilystringAllows users to chose a specific font-family other than the default one.
decorationstringA linear decoration to draw near the text or whether to slant the glyphs in font. none lineThrough underline overline
decorationStylestringThe style in which to paint the text decorations (e.g., dashed). solid double dotted dashed wavy
isItalicbooleanWhether the text should be italic or not
lineHeightMultipleintegerA multiple of the fontSize to determine the line height. (e.g. 2.0 means the line height is double the height the font size occupies). Default null. (note that 1.0 is not the default depending on the font)
letterSpacingintegerThe amount of space (in logical pixels) to add between each letter. A negative value can be used to bring the letters closer.
wordSpacingintegerThe amount of space (in logical pixels) to add at each sequence of white-space (i.e. between each word). A negative value can be used to bring the words closer.
gradientobjectUsing this property we can apply gradient to our text

hintStyles.gradient

PropertyTypeDescription
colorsarrayThe list of colors used for the gradient, which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
stopsarrayThe list of color stops, each is a number between 0.0 (where the gradient starts) and 1.0 (where the gradient ends). The number of stops should match the number of colors.
startstringThe starting position of the gradient,topLeft, topCenter, topRight, centerLeft, center, centerRight, bottomLeft, bottomCenter, bottomRight
endstringThe ending position of the gradient, topLeft, topCenter, topRight, centerLeft, center, centerRight, bottomLeft, bottomCenter, bottomRight

validator

PropertyTypeDescription
minLengthintegerThe minimum number of characters
maxLengthintegerThe maximum number of characters
regexstringThe Regular Expression the input will need to match
regexErrorstringThe customized error message to show when the input does not match the provided regex.

options for styles.variant

OptionDescription
boxdraw a Box border around this input widget. This property can be defined in the theme to apply to all Input widgets.
underlinedraw an Underline below this input widget. This property can be defined in the theme to apply to all Input widgets.

MaxLengthEnforcement

PropertyTypeDescription
nonestringNo enforcement applied to the editing value. It's possible to exceed the maxLength.
enforcedstringKeep the length of the text input from exceeding the max length even when the text has an unfinished composing region.
truncateAfterCompositionEndsstringUsers can still input text if the current value is composing even after reaching the max length limit. After composing ends, the value will be truncated.