The unit input allows for restricted input of values based on the provided unit (distance, weight, temperature, etc.) and locale.
The unit prop is the type of unit you want to display. A full list of allowed unit types are listed below:
The display length can be modified by the unitDisplay property. Accepted values are short, narrow, and long.
By default the locale will use what you have set in your formkit.config.ts as the desired locale. However you can override this with the displayLocale prop. For example, en-US, de-DE, en-IN, zh-CN, etc, etc.
By default the decimals will display when the value contains the unit/locale decimal separator and will show default formatting decimal places to display for the given unit, however you can override this. By setting decimals to false or 0, the value will not allow decimals or setting decimals to a numeric value will limit the maximum decimal places to that value.
You can also choose to set a minimum number of decimals with the minDecimals prop. For example, you always want to show 2 decimal places you would set minDecimals="2".
Similar to a number input, you can set a min and max value.
Again, similar to a number input you can use the up/down keys to step the value. By default the step is 1 but you can override that with this prop.
The value of the input itself defaults to a number but can be formatted as a string to include information about the unit itself.
The unit input also allows for first-party conversion of one unit type to another. In this example, we will use unit of type mile, but the value
itself will be converted to kilometers when setting value-unit to kilometer.
The unit prop is optional, allowing for unitless values.
In order to convert one unit to another, they must be in the same taxonomy (so for example, you can not convert kilometers to liters).
| Prop | Type | Default | Description |
|---|---|---|---|
| unit | string | undefined | Set the specified unit to use for this input. If undefined, will allow for unitless values. | |
| displayLocale | string | en-US | Set the desired display locale to use for this input |
| decimals | boolean|number | null | Choose to either completely disallow decimals or override the maximum number of decimals for the input |
| minDecimals | number | null | Choose to show a minimum number of decimals should your input require this |
| min | number | null | Minimum numeric value allowed. If zero or above, negatives will not be allowed |
| max | number | null | Maximum numeric value allowed for this input |
| step | number | 1 | When using the up/down keys, how much to modify the current value. |
| valueDecimals | string | number | undefined | Determines the allowed number of decimals for the valueUnit. |
| valueFormat | string | number | Choose between number and string whether you want a numeric value or a parsed string value |
| valueUnit | string | undefined | Used to convert the user-inputted value from one unit to another |
| unitDisplay | string ('narrow' | 'short' | 'long') | short | Determines the length of the how the unit is represented. |
| Show Universal props | |||
| config | Object | {} | Configuration options to provide to the input’s node and any descendent node of this input. |
| delay | Number | 20 | Number of milliseconds to debounce an input’s value before the commit hook is dispatched. |
| dirtyBehavior | string | touched | Determines how the "dirty" flag of this input is set. Can be set to touched or compare — touched (the default) is more performant, but will not detect when the form is once again matching its initial state. |
| errors | Array | [] | Array of strings to show as error messages on this field. |
| help | String | '' | Text for help text associated with the input. |
| id | String | input_{n} | The unique id of the input. Providing an id also allows the input’s node to be globally accessed. |
| ignore | Boolean | false | Prevents an input from being included in any parent (group, list, form etc). Useful when using inputs for UI instead of actual values. |
| index | Number | undefined | Allows an input to be inserted at the given index if the parent is a list. If the input’s value is undefined, it inherits the value from that index position. If it has a value it inserts it into the lists’s values at the given index. |
| label | String | '' | Text for the label element associated with the input. |
| name | String | input_{n} | The name of the input as identified in the data object. This should be unique within a group of fields. |
| parent | FormKitNode | contextual | By default the parent is a wrapping group, list or form — but this props allows explicit assignment of the parent node. |
| prefix-icon | String | '' | Specifies an icon to put in the prefixIcon section. |
| preserve | boolean | false | Preserves the value of the input on a parent group, list, or form when the input unmounts. |
| preserve-errors | boolean | false | By default errors set on inputs using setErrors are automatically cleared on input, setting this prop to true maintains the error until it is explicitly cleared. |
| sections-schema | Object | {} | An object of section keys and schema partial values, where each schema partial is applied to the respective section. |
| suffix-icon | String | '' | Specifies an icon to put in the suffixIcon section. |
| type | String | text | The type of input to render from the library. |
| validation | String, Array | [] | The validation rules to be applied to the input. |
| validation-visibility | String | blur | Determines when to show an input's failing validation rules. Valid values are blur, dirty, and live. |
| validation-label | String | {label prop} | Determines what label to use in validation error messages, by default it uses the label prop if available, otherwise it uses the name prop. |
| validation-rules | Object | {} | Additional custom validation rules to make available to the validation prop. |
| value | Any | undefined | Seeds the initial value of an input and/or its children. Not reactive. Can seed entire groups (forms) and lists.. |
You can target a specific section of an input using that section's "key", allowing you to modify that section's classes, HTML (via :sections-schema, or content (via slots)). Read more about sections here.