FormItem

A FormItem component represents a single input element within a Form. The value within the FormItem may be associated with a particular property within the encapsulating Form component's data.

The component provides context values with which you can access some internal properties:

• $setValue: This function can be invoked to set the FormItem instance's value. The function has a single argument, the new value to set.
• $validationResult: This variable represents the result of the latest validation of the FormItem instance.
• $value: The context variable represents the current value of the FormItem. It can be used in expressions and code snippets within the FormItem instance.

You can learn more about this component in the Forms article.

Properties

autoFocus (default: false)

If this property is set to true, the component gets the focus automatically when displayed.

bindTo

This property binds a particular input field to one of the attributes of the Form data. It names the property of the form's data data to get the input's initial value.When the field is saved, its value will be stored in the data property with this name.

Try to enter some kind of text in the input field labelled Lastname and submit the form. Note how the submitted data looks like compared to the one set in data.

<App>
  <Form
    data="{{ firstname: 'James', lastname: 'Clewell' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem label="Firstname" bindTo="firstname" />
    <FormItem label="Lastname" />
  </Form>
</App>

customValidationsDebounce (default: 0)

This optional number prop determines the time interval between two runs of a custom validation.

Note how changing the input in the demo below will result in a slight delay of input checks noted by the appearance of a new "I" character.

<App>
  <Form
    var.validations="Validations: "
    data="{{ name: 'Joe' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem
      customValidationsDebounce="3000"
      onValidate="(value) => { validations += '| '; return value === value.toUpperCase(); }"
      bindTo="name" />
    <Text value="{validations}" />
  </Form>
</App>

enabled (default: true)

This boolean property value indicates whether the component responds to user events (true) or not (false).

<App>
  <Form>
    <FormItem label="Firstname" enabled="true" />
    <FormItem label="Lastname" enabled="false" />
  </Form>
</App>

initialValue

This property sets the component's initial value.

<App>
  <Form data="{{ firstname: 'Michael', lastname: undefined }}">
    <FormItem label="Firstname" bindTo="firstname" initialValue="James" />
    <FormItem label="Lastname" bindTo="lastname" initialValue="Jordan" />
  </Form>
</App>

inputTemplate

This property is used to define a custom input template.

label

This property sets the label of the component.

<App>
  <Form>
    <FormItem label="Firstname" />
  </Form>
</App>

labelBreak (default: true)

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

Different input components have different layout methods (i.e. TextBox labels are positioned at the top, Checkbox labels are on the right side).

<App>
  <Form>
    <FormItem label="Start Label" labelPosition="start" />
    <FormItem label="Top Label" labelPosition="top" />
    <FormItem label="End Label" labelPosition="end" />
    <FormItem label="Bottom Label" labelPosition="bottom" />
  </Form>
</App>

labelWidth

This property sets the width of the item label.

lengthInvalidMessage

This optional string property is used to customize the message that is displayed on a failed length check: minLength or maxLength.

In the app, type a name longer than four characters in both fields, then leave the edited field. The two fields will display different error messages; the second uses the customized one.

<App>
  <Form
    data="{{ firstname: 'James', lastname: 'Clewell' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem maxLength="4" bindTo="firstname" />
    <FormItem lengthInvalidMessage="Name is too long!" maxLength="4" bindTo="lastname" />
  </Form>
</App>

lengthInvalidSeverity (default: "error")

This property sets the severity level of the length validation.

Available values: error (default), warning, valid

In the app, type a name longer than four characters in both fields, then leave the edited field. The two fields will display different error messages; the second uses a warning instead of an error.

<App>
  <Form
    data="{{ firstname: 'James', lastname: 'Clewell' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem maxLength="4" bindTo="firstname" />
    <FormItem lengthInvalidSeverity="warning" maxLength="4" bindTo="lastname" />
  </Form>
</App>

maxLength

Checks whether the input has a maximum length of a specified value.

Note that it is not possible for the user to enter a string larger than the value of the maxLength, but setting such a value programmatically still results in a validation check.

In the demo below, try to enter an input longer than 4 characters or submit the form as is.

<App>
  <Form
    data="{{ firstname: 'James' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem maxLength="4" bindTo="firstname" />
  </Form>
</App>

maxTextLength

The maximum length of the text in the input field

maxValue

Checks whether the input has the maximum specified value.

Note that it is not possible for the user to enter a number larger than the value of the maxValue, but setting such a value programmatically still results in a validation check.

In the demo below, enter an input greater than 99 or just submit the form as is.

<App>
  <Form
    data="{{ age: 100 }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem maxValue="99" bindTo="age" type="integer" />
  </Form>
</App>

minLength

Checks whether the input has a minimum length of a specified value.

In the demo below, enter an input shorter than 4 characters or just submit the form as is.

<App>
  <Form
    data="{{ firstname: '' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem minLength="4" bindTo="firstname" />
  </Form>
</App>

minValue

Checks whether the input has the minimum specified value.

Note that it is not possible for the user to enter a number smaller than the value of the minValue, but setting such a value programmatically still results in a validation check.

In the demo below, enter an input smaller than 18 or just submit the form as is.

<App>
  <Form
    data="{{ age: 0 }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem minValue="18" bindTo="age" type="integer" />
  </Form>
</App>

pattern

Checks whether the input fits a predefined regular expression.

Note: To define custom patterns and regular expressions, see the regex section.

In the demo below, enter an input that is not solely one lowercase string or just submit the form as is.

<App>
  <Form
    data="{{ userEmail: 'mailto' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem pattern="email" bindTo="userEmail" />
  </Form>
</App>

patternInvalidMessage

This optional string property is used to customize the message that is displayed on a failed pattern test.

In the demo below, enter anything that does not look like an email and click outside to see the regular and custom message.

<App>
  <Form
    data="{{ oldEmail: 'mailto', newEmail: 'mailto' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem pattern="email" bindTo="oldEmail" />
    <FormItem
      patternInvalidMessage="This does not look like an email"
      pattern="email" bindTo="newEmail" />
  </Form>
</App>

patternInvalidSeverity (default: "error")

This property sets the severity level of the pattern validation.

Available values: error (default), warning, valid

In the demo below, enter a string of characters that does not look like an email to see the difference in feedback.

<App>
  <Form
    data="{{ oldEmail: 'mailto', newEmail: 'mailto' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem pattern="email" bindTo="oldEmail" />
    <FormItem patternInvalidSeverity="warning" pattern="email" bindTo="newEmail" />
  </Form>
</App>

rangeInvalidMessage

This optional string property is used to customize the message that is displayed when a value is out of range.

In the demo below, enter any value that is out of range in the input fields and click outside to see the regular and custom message. Just submitting the form as is also produces the same error.

<App>
  <Form
    data="{{ age: 100, customAge: 100 }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem minValue="0" maxValue="99" bindTo="age" type="integer" />
    <FormItem
      minValue="0"
      maxValue="99"
      rangeInvalidMessage="Out of range!"
      bindTo="customAge"
      type="integer" />
  </Form>
</App>

rangeInvalidSeverity (default: "error")

This property sets the severity level of the value range validation.

Available values: error (default), warning, valid

In the demo below, enter any value that is out of range in the input fields and click outside to see the regular and custom message. Just submitting the form as is also produces the same error.

<App>
  <Form
    data="{{ age: 100, customAge: 100 }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem minValue="0" maxValue="99" bindTo="age" type="integer" />
    <FormItem
      minValue="0" maxValue="99"
      rangeInvalidSeverity="warning"
      bindTo="customAge"
      type="integer" />
  </Form>
</App>

regex

Checks whether the input fits the provided regular expression.

In the demo below, enter an input that is not solely one lowercase string or just submit the form as is.

<App>
  <Form
    data="{{ password: 'PASSWORD123' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem regex="^[a-z]+$" bindTo="password" />
  </Form>
</App>

regexInvalidMessage

This optional string property is used to customize the message that is displayed on a failed regular expression test.

In the demo below, enter a password that is not a lowercase string and click outside to see the regular and custom message.

<App>
  <Form
    data="{{ oldPassword: 'PASSWORD123', newPassword: 'PASSWORD123' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem regex="^[a-z]+$" bindTo="oldPassword" />
    <FormItem
      regexInvalidMessage="Password must be all lowercase"
      regex="^[a-z]+$" bindTo="newPassword" />
  </Form>
</App>

regexInvalidSeverity (default: "error")

This property sets the severity level of regular expression validation.

Available values: error (default), warning, valid

In the demo below, enter a password that is not a lowercase string and click outside to see the regular and custom message. Just submitting the form as is also produces the same error.

<App>
  <Form
    data="{{ oldPassword: 'PASSWORD123', newPassword: 'PASSWORD123' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem regex="^[a-z]+$" bindTo="oldPassword" />
    <FormItem regexInvalidSeverity="warning" regex="^[a-z]+$" bindTo="newPassword" />
  </Form>
</App>

required

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

<App>
  <Form
    data="{{ name: undefined }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem required="true" label="Name" bindTo="name" />
  </Form>
</App>

requiredInvalidMessage

This optional string property is used to customize the message that is displayed if the field is not filled in.

In the demo below, leave the field empty and click outside to see the regular and custom message.

<App>
  <Form
    data="{{ firstname: undefined, lastname: undefined }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem required="true" label="First Name" bindTo="firstname" />
    <FormItem
      requiredInvalidMessage="Last Name is required!"
      required="true"
      label="Last Name"
      bindTo="lastname" />
  </Form>
</App>

type (default: "text")

This property is used to determine the specific input control the FormItem will wrap around. Note that the control names start with a lowercase letter and map to input components found in XMLUI.

Available values:

validationMode (default: "errorLate")

This property sets what kind of validation mode or strategy to employ for a particular input field.

Available values:

Events

validate

This event is used to define a custom validation function.

In the demo below, leave the field as is and submit the form or enter an input that is not all capital letters.

<App>
  <Form
    data="{{ name: 'James' }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FormItem
      bindTo="name"
      onValidate="(value) => value === value.toUpperCase()" />
  </Form>
</App>

Exposed Methods

This component does not expose any methods.

Styling

FormItem supports the styling of labels through these theme variables:

• textColor-FormItemLabel
• fontSize-FormItemLabel
• fontWeight-FormItemLabel
• fontStyle-FormItemLabel
• textTransform-FormItemLabel
• textColor-FormItemLabel-required
• fontSize-FormItemLabel-required
• fontWeight-FormItemLabel-required
• fontStyle-FormItemLabel-required
• textTransform-FormItemLabel-required
• textColor-FormItemLabel-requiredMark

This component displays other input components and binds them with the form's logic. You can style the individual form components; see the type property to check what components are used beyond a particular form item.

Theme Variables