UnitPro

FormKit Pro Quick Installation Guide 🚀

Unit Input

The unit input allows for restricted input of values based on the provided unit (distance, weight, temperature, etc.) and locale.

<FormKit  type="unit"  unit="kilometer"  name="distance"  label="Distance in meters"/><FormKit  type="unit"  unit="celsius"  name="temperature"  label="Temperature in Celsius"/><FormKit  type="unit"  unit="nanosecond"  name="time"  label="Time in nanoseconds"/><FormKit  type="unit"  unit="fluid-ounce"  name="volume"  label="Volume in fluid ounces"/><FormKit  type="unit"  unit="megabyte"  name="digital-unit"  label="Digital unit in megabytes"/><pre wrap>{{ value }}</pre>

Distance in meters

Temperature in Celsius

Time in nanoseconds

Volume in fluid ounces

Digital unit in megabytes

{
  "distance": 100,
  "temperature": 100,
  "time": 100,
  "volume": 100,
  "digital-unit": 100
}

Props

Unit

The unit prop is the type of unit you want to display. A full list of allowed unit types are listed below:

acre
bit
byte
celsius
centimeter
day
degree
fahrenheit
fluid-ounce
foot
gallon
gigabit
gigabyte
gram
hectare
hour
inch
kilobit
kilobyte
kilogram
kilometer
liter
megabit
megabyte
meter
microsecond
mile
mile-scandinavian
milliliter
millimeter
millisecond
minute
month
nanosecond
ounce
percent
petabyte
pound
second
stone
terabit
terabyte
week
yard
year

Unit display

The display length can be modified by the unitDisplay property. Accepted values are short, narrow, and long.

<FormKit  type="unit"  unit="kilogram"  name="narrow"  unit-display="narrow"  label="Narrow"/><FormKit  type="unit"  unit="kilogram"  name="short"  unit-display="short"  label="Short"/><FormKit  type="unit"  unit="kilogram"  name="long"  unit-display="long"  label="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.

<FormKit  type="unit"  unit="kilogram"  name="input_1"  unit-display="long"  display-locale="en-US"/><FormKit  type="unit"  unit="kilogram"  name="input_2"  unit-display="long"  display-locale="de-DE"/><FormKit  type="unit"  unit="kilogram"  name="input_3"  unit-display="long"  display-locale="zh-CN"/>

Decimals

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

<FormKit  type="unit"  unit="liter"  name="input_1"  label="5 decimals allowed"  decimals="5"/><FormKit  type="unit"  unit="liter"  name="input_2"  label="Minimum of 2 decimals"  min-decimals="2"/>

Minimum and Maximum Values

Similar to a number input, you can set a min and max value.

<FormKit  type="unit"  unit="millisecond"  name="input_1"  label="Min of 100"  min="100"/><FormKit  type="unit"  unit="millisecond"  name="input_2"  label="Max of 100"  max="100"/>

Step

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.

<FormKit  type="unit"  unit="centimeter"  name="input_1"  label="Step of 100"  step="100"/>

Value Formatting

The value of the input itself defaults to a number but can be formatted as a string to include information about the unit itself.

<FormKit  type="unit"  unit="year"  name="input_1"  label="Default formatting"/><FormKit  type="unit"  unit="year"  name="input_2"  label="Formatting as string"  value-format="string"/><pre wrap>{{ value }}</pre>

Default formatting

Formatting as string

{
  "input_1": 100,
  "input_2": 100
}

Value unit

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.

<template>  <FormKit v-slot="{ value }" type="form" :actions="false">    <FormKit      type="unit"      unit="mile"      label="Miles"      name="value"      value-unit="kilometer"    />    <pre wrap>In kilometers: {{ value && value.value }}</pre>  </FormKit></template>

Miles

In kilometers:

Unitless

The unit prop is optional, allowing for unitless values.

<template>  <FormKit v-slot="{ value }" type="form" :actions="false">    <FormKit type="unit" label="No units" name="value" />    <pre wrap>{{ value && value.value }}</pre>  </FormKit></template>

No units

Mixed unit types

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

Props & Attributes

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

Sections

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.

Unit input diagram

outer

wrapper

label

Unit Input

inner

prefixIcon

prefix

input

100 mi

suffix

suffixIcon

help

Help text goes here.

messages

message

Any messages would appear here.

Click on a section to lock focus to the chosen section. Click locked section again to unlock.

Accessibility

All FormKit inputs are designed with the following accessibility considerations in mind. Help us continually improve accessibility for all by filing accessibility issues here:

Semantic markup
ARIA attributes
Keyboard accessibility
Focus indicators
Color contrast with the provided theme
Accessible labels, help text, and errors

Accessibility attributes

Section Key	Attribute	Value	Description
`label`	`label`	`for`	Associates a label to an input element. Users can click on the label to focus the input or to toggle between states.
`input`	`input`	`disabled`	Disables an HTML element, preventing user interaction and signaling a non-interactive state.
		`aria-describedby`	Associates an element with a description, aiding screen readers.
		`aria-required`	Added when input validation is set to `required`.
`icon`	`icon`	`for`	Links icon to input element when icon in rendered as a `label`.

Keyboard Interactions

Keyboard Event	Description
`↑↓`	Increments through input value by current `step` amount.
Universal Keyboard Events
`Tab`	Moves the focus to the next focusable element on the page.
`Shift`+`Tab`	Moves the focus to the previous focusable element on the page.