Inputs

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.

Input types

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.

Text input

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:

Textarea

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:

Password Input

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:

Number Input

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:

Percent Input

The Email Input and URL Input are standard text inputs, but validate the entered value for correctness:

Email and URL Input

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:

Slider Input

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:

Date, Time, Date & Time and Date Range Inputs

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:

Handling invalid input

Label positioning

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:

Label position is determined by component size automatically

Switching types

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:

1. Values of properties that both input types have in common (e.g. the "Disabled" property) will remain the same.

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

3. Existing validation rules will always be dropped entirely.

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

Validation rules

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

Validation trigger

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.

Impact of the "Validate while typing" property

Rule execution

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.

"Required" validation

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.

Minimum length & Maximum length

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.

Minimum value & Maximum value

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.

Email

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.

URL

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.

Regular expression

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.

Before, After, Before time, After time

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

Custom action

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.

Properties

All input components share the following set of configuration properties:

Property	Type	Default value	Behavior
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	This property is used to switch an input to another type. Learn more
Label	stringWithJs	Depends on input type	Text that is displayed as label of the input, either to its left or above. Learn more
Label alignment	'left' | 'center' | 'right'	'left'	Text alignment of the label.
Required	boolean	false	Determines whether the input is considered invalid without a value. Learn more about this special kind of validation rules here
Validate while typing	boolean	true	Determines whether the validation rules should be evaluated on every change of the input value, or only on surrounding Form submit. Learn more
Validation rules	List	None, except for Email Input and URL Input	Set of validation rules that are applied on the configured trigger. Learn more

Custom properties of textual inputs

This includes the Text Input, Textarea, Password Input, Email Input and URL Input:

Property	Type	Default value	Behavior
Default value	stringWithJs	''	Initital value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding Form, is triggered.
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.

Custom properties of numeric inputs

This includes the Number Input and the Percent Input:

Property	Type	Default value	Behavior
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	''	Initial value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding Form, 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.
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.

Custom properties of date/time inputs

This includes the Date Input, Time Input and the Date & Time Input:

Property	Type	Default value	Behavior
Custom date format	stringWithJs	'yyyy-MM-dd'	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 date-fns.format.
Custom time format	stringWithJs	'HH:mm'	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 date-fns.format.
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	Initial value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding Form, 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.
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

Property	Type	Default value	Behavior
Default start date	js	null	Initial value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding Form, is triggered. The JavaScript expression should either evaluate to a Date object, or an ISO 8601 date string.
Default end date	js	null	Initial value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding Form, is triggered. The JavaScript expression should either evaluate to a Date object, or an ISO 8601 date string.
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

Property	Type	Default value	Behavior
Default value	js	1	Initial value of the input on app load. Also, this value is set when the reset() API method of the input, or a surrounding Form, is triggered. The JavaScript expression should evaluate to a Number.
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.

Custom properties of file input

Property	Type	Default value	Behavior
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.

Events

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.

API

All input components share the following properties and methods in their JavaScript API:

Property / Function	Type	Behavior
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.

API of textual inputs

This includes the Text Input, Textarea, Password Input, Email Input and URL Input:

Property / Function	Type	Behavior
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.

API of numeric inputs

This includes the Number Input and the Percent Input:

Property / Function	Type	Behavior
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.

API of date/time inputs

This includes the Date Input, Time Input, Date & Time Input and Date Range Input:

Property / Function	Type	Behavior
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

Property / Function	Type	Behavior
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.

API of the file input

Property / Function	Type	Behavior
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.