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

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:

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:

### 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. {% hint style="info" %} 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. {% endhint %} ### 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](https://docs.uify.io/component-reference/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](https://docs.uify.io/component-reference/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](#validation-trigger)). The action execution will receive the current input value as [argument](https://docs.uify.io/writing-code/actions/execution-model#action-arguments), 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. |