Inputs
Last updated
Last updated
Input fields are essential building blocks of almost any application. Such fields target specific types of content, like simple text, numbers, passwords or dates. For this purpose, Uify offers many different input field components targeting those different content types.
Due to similarities in their UI/UX, those components have many configuration properties and API fields in common, but expose a few custom properties that are specific to their particular functionality. This page introduces all input components by describing the shared properties first, and then covering the specific properties of each component separately.
The most basic input field is a simple Text Input. It allows to enter single-line text without any line breaks and is perfectly suited for short inputs like names, street names, etc.
In case single-line text is not suitable and a larger amount of text should be entered, the Textarea is a better fit. It allows to display more than one line of text and to enter line breaks as well:
A more specific type of inputs is the Password Input. It hides the input, unless the user deliberately decides to make the entered value visible by clicking on the icon on the right:
Another specialized input type is the Number Input. It accepts numeric input only, and can be configured to accept negative values and decimal values. The arrow buttons on the right allow incrementing or decrementing the input value by mouse click:
Another number-based input is the Percent Input. It offers the same UX and functionality of the Number Input, but auto-appends the percentage sign. The value of this input is exposed as decimal value, for example "25%" will be programmatically exposed as the decimal 0.25:
The Email Input and URL Input are standard text inputs, but validate the entered value for correctness:
The Slider Input is an intuitive way to quickly set a value within a range with a certain step size without the need to type a numerical value:
The File Input allows users to upload a digital file from their device to be used by an appropriate endpoint:
Last but not least, the Date Input, Time Input, Date & Time and Date Range Input allow the user to enter temporal values. The format is fully configurable and convenient date- and time-pickers make it easy to find the right value. A manual entry and adjustment of the value is possible as well:
In case the user enters a value that is not a valid date or time, according to the configured format, the value is set to the current date and/or time when the input loses focus. This guarantees that if the input contains a value, it will always be valid:
There are two options where the input label can be positioned: To the left of the input, or on top of it. This is automatically adjusted based on the size of the component. The label will be placed above the input as soon as there is enough space for it. Otherwise, the label is positioned to the left of the input in the same line. All inputs except the Textarea will never expand beyond a single line of input. Since the Textarea may contain multi-line content though, it will take the remaining vertical space of the component entirely:
You may change the type of an existing input component by changing the "Input type" property in the properties panel. This will have the following effects on the configured properties of the input component:
Values of properties that both input types have in common (e.g. the "Disabled" property) will remain the same.
Values of properties that do not exist in the target input type (e.g. the "Allow decimals" property of a Numbers Input, which does not exist for the Text Input) will be discarded.
Existing validation rules will always be dropped entirely.
When switching to the Email Input or URL Input, the respective validation rules will be added.
Due to effect 2. and 3., switching an input component to another type, and then back to the initial type, might not result in exactly the same property settings. Therefore, please be careful and aware of these effects when switching input types.
Validating user input is a very common requirement in many applications. You may attach any of the predefined validation rules to input components, or you can create validation actions with custom logic yourself. These validation rules are managed in the properties panel. Some input types have validation rules pre-configured (e.g. the Email Input and the URL Input).
One fundamental decision that you need to make: Should validation rules be applied on every key stroke (i.e. the user will receive immediate feedback while typing) or only on submit of a surrounding Form component? This is configured via the "Validate while typing" property. Especially in case the validation is complex, for example because it involves interactions with external data sources, it is highly recommended to disable this setting. In case however you would like to validate an input component outside of a Form context, this setting should be enabled because the validation will otherwise never happen.
In case an input has multiple rules configured, all rules are executed in parallel, not sequentially. This means, that all rules will always be executed and evaluation is not eagerly aborted in case one rule has already failed. Due to this execution model, the error message presented to the user will always include all messages from all failing validations.
The "Required" property is a special kind of validation, because it is not listed among the validation rules. When this setting is enabled, an input without value is considered invalid when validations are triggered. Being "without value" has a different meaning for different input types:
Text, Textarea, Email, URL, Password: These inputs are considered to not have a value when the length of the value is 0.
Number, Percent: When these inputs do not contain at least one digit, they are considered to not have a value.
Date, Time, Date & Time, Date Range: These inputs do not contain a value in case the input is cleared entirely. Since these inputs are filled with the current date and time in case the user enters an invalid value, this state is fairly well-defined.
This validation is triggered according to the same logic like other validation rules: When "Validate while typing" is enabled, this condition is checked on every change of the input value, otherwise only when a surrounding Form is submitted.
These rules are available for all textual inputs: Text, Textarea, Email, URL, Password. They require the input value to have a minimum or maximum amount of characters to be valid. The constraint value is configured with a JavaScript input, i.e. the limit can contain dynamic code that will be evaluated before the validation rule is applied.
These rules are available for numeric inputs: Number and Percent. The limits are entered with a JavaScript input, i.e. it may be highly dynamic. In case of the percent input, the limit should be entered as a decimal value, e.g. a minimum or maximum of 25% should be entered as 0.25, not as 25.
Available for Text Input, Textarea and Email Input. It requires the input value to be a valid email address. This validation rule is automatically added to instances of the Email Input component.
Available for Text Input, Textarea and URL Input. This rule can be configured to require a specific protocol (for example, HTTP, HTTPS or FTP). If no protocol is configured, a URL without protocol prefix is accepted (e.g. google.com), otherwise the protocol prefix must be provided for the value to be accepted. In addition to this, a comma-separated list of accepted domains can be provided. In case the entered value is not among the configured domains, the value is considered to be invalid and a warning is presented to the user. The input for configuring these domains is a simple text input, but may contain dynamic JavaScript expressions with the {{ ... }} syntax.
This validation rule is automatically added to instances of the URL Input component.
Available for all textual inputs: Text, Textarea, Email, URL, Password. The input for the RegEx is a text input, which may contain dynamic JavaScript expressions with the {{ ... }} syntax. You may enter the pattern with or without /, but if you decide to include them, you need to include them both at the beginning and the end. You may add modifiers and the special indicators ^ and $, i.e. for example /^\d+\sabc$/i is a perfectly valid input.
Available for the textual inputs Date, Time and Date&Time. These rules define that the entered date or time must be before or after the configured threshold. The threshold is entered with a JavaScript input, i.e. it is expected to always be a dynamic expression. It may evaluate to a JavaScript Date, like e.g. new Date(2022, 11, 1) or an ISO date string, like e.g. '2022-12-01'. The "Before time" and "After time" rules will also accept a time string in the format HH:mm, like e.g. '14:33'.
This validation rule is available for all input types. The associated action will be executed every time the validation rules are evaluated (see triggers). The action execution will receive the current input value as argument, so that it is easily available for applying validation logic. The return value of the action will be used as follows:
A falsy return value means that the value is not valid. The default error message will be shown to the user. Since undefined is considered falsy as well, custom validation actions should always return a value explicitly.
A return value of type string will be used as custom error message. In this case, the value will be considered invalid, and the returned string will be displayed to the user as error message. Please note that the empty string is falsy, and will hence mean an invalid value. The default error message will be shown to the user in this case.
A truthy return value, except for a value of type string, means that the input value is valid.
In case the action throws an error, the value is considered invalid and a default error message is shown accordingly.
All input components share the following set of configuration properties:
Disabled
boolean
false
Determines whether the input is disabled or not. When disabled, the user cannot focus the input and cannot modify the value. Validation rules are however applied either way.
Input type
string
Depends on input type
Label
stringWithJs
Depends on input type
Label alignment
'left' | 'center' | 'right'
'left'
Text alignment of the label.
Required
boolean
false
Validate while typing
boolean
true
Validation rules
List
None, except for Email Input and URL Input
This includes the Text Input, Textarea, Password Input, Email Input and URL Input:
Default value
stringWithJs
''
Placeholder
stringWithJs
'Enter value' | 'Enter password'
Text that is displayed in the input when no value has been entered yet.
Show clear icon
boolean
false
Determines whether an "x" icon will be shown when a value has been entered. Clicking this icon will clear the input entirely. Does not apply to Password Input and Textarea.
This includes the Number Input and the Percent Input:
Allow decimals
boolean
false
Determines whether the user may enter decimal values. The decimal separator is always the dot (.). This setting also influences how pasting works - in case this setting is set to false, the decimal point and potential decimals will be cut off when pasted.
Allow negative
boolean
false
Determines whether the user may enter negative values, or decrement the value beyond zero with the button controls. Also, when enabled, the user may paste a numeric text that begins with a dash. Otherwise, the paste is ignored.
Default value
js
''
Placeholder
stringWithJs
'Enter number'
Text that is displayed in the input when no value has been entered yet.
Show controls
boolean
true
Determines whether the increment and decrement button will be displayed to the right of the input. Those controls allow to increment and decrement the value with mouse click.
This includes the Date Input, Time Input and the Date & Time Input:
Custom date format
stringWithJs
'yyyy-MM-dd'
Custom time format
stringWithJs
'HH:mm'
Date format
string
'yyyy-MM-dd'
Display format of the date part in the input, and which is used to parse the input value in case of manual input. This setting also influence the format of the valueFormattedString API property.
Default value
js
null
First day of week
'Sunday' | 'Monday'
'Sunday'
This setting influences the first day of the week in the date picker.
Show clear icon
boolean
false
Determines whether an "x" icon will be shown when a value has been entered. Clicking this icon will clear the input entirely.
Time format
string
'HH:mm'
Display format of the time part of the input value, and format that is used to parse the input value in case of manual input. This setting also influence the format of the valueFormattedString API property.
Custom inputs of date range
Default start date
js
null
Default end date
js
null
Placeholder start date
js
null
Placeholder end date
js
null
Date format
string
'yyyy-MM-dd'
Display format of the date part in the input, and which is used to parse the input value in case of manual input. This setting also influence the format of the valueFormattedString API property.
First day of week
'Sunday' | 'Monday'
'Sunday'
This setting influences the first day of the week in the date picker.
Show clear icon
boolean
false
Determines whether an "x" icon will be shown when a value has been entered. Clicking this icon will clear the input entirely.
Custom properties of slider inputs
Default value
js
1
Minimum value
js
1
The JavaScript expression should evaluate to a Number.
Maximum value
js
5
The JavaScript expression should evaluate to a Number. Note that the maximum may never be reached if it does not equal the sum of the minimum value and a multiple of the step size.
Step size
js
1
The JavaScript expression should evaluate to a Number. The step size describes in which increments the value of the slider increases when the slider is dragged.
Allowed file types
js
null
If you want to restrict the types of files that a user can upload, you simply provide an array of file extensions to whitelist them. If it is empty, it allows all file types.
Allow multiple files
boolean
false
Defines if the user can select and upload multiple files.
All input components offer the same set of UI events:
On change: This event is triggered whenever the input value changes, e.g. because the user is typing, has pasted new content or has cleared the input by clicking on the clear-icon. This event is not triggered when the value changes programmatically via the setValue, clear or reset methods.
On blur: This event is triggered when the input loses focus.
All input components share the following properties and methods in their JavaScript API:
clear()
() => void
Clears the input, i.e. sets the input for the empty string for textual input types, and to null for all others.
disabled
boolean
Current value of the "Disabled" property.
label
string
Current value of the "Label" property.
reset()
() => void
Sets the value of the input to the current value of the "Default value" property. This is useful when a form or individual component should not just be emptied, but instead reset to what it was initially on app load.
setDisabled(value)
(value: boolean) => void
Sets the "Disabled" property to the provided value.
setLabel(value)
(value: string) => void
Sets the "Label" property to the provided value.
validate()
() ⇒ Promise
We return a Promise that runs all validation rules for the current value. When the promise resolves, a boolean is returned. If true is returned, the input is valid, otherwise it is invalid.
This includes the Text Input, Textarea, Password Input, Email Input and URL Input:
passwordVisibility
boolean
true in case the input value is currently visible as clear text, i.e. the user clicked the visibility icon, false otherwise. Only for Password Input.
placeholder
string
Current value of the "Placeholder" property.
setPasswordVisibility(value)
(value: boolean) => void
Sets the password visibility, i.e. the password is displayed as clear text when true is provided as argument, otherwise the password is hidden. Only for Password Input.
setPlaceholder(value)
(value: string) => void
Sets the "Placeholder" property to the provided value.
setValue(value)
(value: string) => void
Sets the input value to the provided value.
value
string
Current value of the input.
This includes the Number Input and the Percent Input:
allowDecimals
boolean
Current value of the "Allow decimals" property.
allowNegative
boolean
Current value of the "Allow negative" property.
placeholder
string
Current value of the "Placeholder" property.
setAllowDecimals(value)
(value: boolean) => void
Sets the "Allow decimals" property to the provided value.
setAllowNegative(value)
(value: boolean) => void
Sets the "Allow negative" property to the provided value.
setPlaceholder(value)
(value: string) => void
Sets the "Placeholder" property to the provided value.
setValue(value)
(value: number | null) => void
Sets the input value to the provided value. In case null is provided, the input is cleared. In case a negative value is provided, but the "Allow negative" property is currently set to false, the input value is set to 0. In case a decimal value is provided, but the "Allow decimals" property is set to false, the decimals are cut off.
value
number | null
Provides the current value of the input. null in case no value has been entered, otherwise a number.
This includes the Date Input, Time Input, Date & Time Input and Date Range Input:
setValue(value)
(value: string | Date | null) => void (except date range input: (value: {state: string | Date | null, end: string | Date | null})
Sets the input value to the provided value. In case null is provided, the input is cleared. In case a Date object is provided, the date and time parts are filled according to its values. In case of an argument of type string, the string is expected to either be an ISO 8601 string, or a string that is formatted according to the "Date format" and "Time format" (or, "Custom date format" / "Custom time format") properties. Otherwise, an error is thrown.
value
Date | null (excpet date range input: {state: Date | null, end: Date | null})
Provides the current value of the input. null in case no value has been entered, otherwise a Date object. In case of a Date Input, the time part of the Date will be 00:00:00.
valueFormattedString
string | null
Provides the current value of the input as a formatted string, using the formats from the "Date format" / "Custom date format" / "Time format" / "Custom time format" properties. null in case the input currently has no value. Date and time parts are separated by a space (' ').
valueISOString
string | null
Provides the current input value as a string in ISO 8601 format. null in case the input currently has no value. For a Time input, the value is formatted as HH:mm. The Date Input uses yyyy-MM-dd.
API of the slider
maximum
number
Current value of "Maximum" property.
setMaximum(value)
(value: number) => void
Sets the "Maximum" property to the provided value.
minimum
number
Current value of "Minimum" property.
setMinimum(value)
(value: number) => void
Sets the "Minimum" property to the provided value.
stepSize
number
Current value of "Step Size" property.
setStepSize(value)
(value: number) => void
Sets the "Step Size" property to the provided value.
value
number
Current value of the input.
setValue(value)
(value: number) => void
Sets the value to the provided value.
files
{name: string, size: number, type: string}[]
The file names, their sizes and types that were uploaded.
multiple
boolean
Returns if the file input allows multiple files.
setMultiple(value)
(value: boolean) => void
Set the "Allow multiple files" property.
accept
string[]
Returns a list of file extensions that are allowed.
setAccept(value)
(value: string[]) => void
Set the file extensions that are allowed to be uploaded.
This property is used to switch an input to another type.
Text that is displayed as label of the input, either to its left or above.
Determines whether the input is considered invalid without a value. Learn more about this special kind of validation rules
Determines whether the validation rules should be evaluated on every change of the input value, or only on surrounding submit.
Set of validation rules that are applied on the configured trigger.
Initital value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding , is triggered.
Initial value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding , is triggered. This JavaScript expression is supposed to evaluate to a value of type number. Otherwise, it is ignored and the input is kept empty. In case the given value does not comply with the configured rules, e.g. the value is negative but the "Allow negative" property is set to false, the value is anyway used as input value.
Custom format to be used instead of the preconfigured options of the "Date format" property. Only available when the "Date format" property is set to "Custom". The format should be written as described for .
Custom format to be used instead of the preconfigured options of the "Time format" property. Only available when the "Time format" property is set to "Custom". The format should be written as described for .
Initial value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding , is triggered. The JavaScript expression should either evaluate to a Date object, or an ISO 8601 date string. For a Time Input, a time string in the format of HH:mm, like e.g. '14:30', is allowed as well.
Initial value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding , is triggered. The JavaScript expression should either evaluate to a Date object, or an ISO 8601 date string.
Initial value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding , is triggered. The JavaScript expression should either evaluate to a Date object, or an ISO 8601 date string.
Initial value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding , is triggered. The JavaScript expression should evaluate to a Number.
