FormKit’s inputs are similar to HTML inputs but turbocharged with much needed features like labels, help text, validation, and error messages (and much more). Similar to how HTML’s <input> tag uses various type attributes (i.e., <input type="text"> vs <input type="checkbox">), FormKit uses the type prop for all inputs. In fact, with FormKit, there is only 1 component you have to learn:
FormKit inputs are not confined to what is available in "native" HTML. The upcoming FormKit Pro represents "synthetic" input types such as autocomplete, taglist and wysiwyg. Of course, you can write your own inputs too by creating custom inputs.
There are 4 ways to set the value of an input:
value prop.v-model.node.input() method.FormKit component.value propYou can set the value of a single input or a group of inputs using the value
prop.
value prop should only be used for setting the initial value of an input. It will not react to changes after the component has been created.
v-modelUsing v-model allows for two-way reactive data binding with any FormKit input.
node.input()At the heart of every FormKit input is an instance of FormKit’s node
object, and using the node.input() method is the most efficient mechanism to modify any input’s value (read more about getting an instance of the node object).
node.input() are debounced, and thus asynchronous (use the delay prop to change the length of the debounce). You can await node.input(val) to determine when the input has settled.
Parent inputs like list, group, and form are also able to directly set the values of any of their children. In fact, the value of a parent is just the aggregate value of its children. You can use any of the above methods (value prop, v-model, or node.input()) to set the value of the children.
In nearly all cases, attributes set on the <FormKit> component will be passed through to the actual <input> element at the heart of the component, rather than any wrapping DOM elements. For example:
We discuss validation in more detail on its own documentation page — but suffice to say adding validation rules to inputs in FormKit is as easy as adding the validation prop:
For performance, all FormKit inputs support debouncing as a first-class feature. While the value of an input changes on every keystroke (technically the input event), this newly updated value is only set internally — validation rules, groups, lists, forms, and (most) plugins are not yet “aware” a change has been made.
Internally, FormKit debounces the input event. When the debounce has "settled", the new value is “committed” and the rest of the application is then notified via the input node’s commit event. The default debounce delay is 20 milliseconds and can be adjusted with the delay prop or config option.
To illustrate this, let's v-model a group input and observe how its value is not updated until after our egregiously long delay:
20 milliseconds. However, group and list inputs use 0 milliseconds by default to prevent the debounce delay from “building up” at each level of depth.
Validation errors are not the only way to set errors on an input. You can also explicitly set error messages on an input by using the errors prop.
FormKit inputs accept both universal props (ones that apply to all FormKit inputs), and input-specific props. The following table is a comprehensive list of props available to all FormKit inputs.
| Prop | Type | Default | Description |
|---|---|---|---|
| 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. |
| 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. |
| 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. |
| preserve | boolean | false | Preserves the value of the input on a parent group, list, or form when the input unmounts. |
| sections-schema | Object | {} | An object of section keys and schema partial values, where each schema partial is applied to the respective 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. |
FormKit inputs emit both universal events (ones that are emitted from all inputs), and input-specific events. The following table is a comprehensive list of events emitted by all FormKit inputs.
| Event | Payload | Description |
|---|---|---|
| input | any | Emitted when the core node’s commit hook is completed (after input debounce). |
| node | FormKitNode | Emitted when the component’s setup is complete. This is the internal FormKitNode object at the heart of the input. |
Inputs are composed of chunks of HTML called "sections". Each section has a "key" that can be used to target that section. Section keys can be used for many purposes like modifying classes, slots, and extending each sections’s schema.
Many section keys are universally available while others are specific to a given input type (you can define your own for custom inputs as well). The following table is a comprehensive list of those that are generally available in all inputs:
| Section-key | Description |
|---|---|
| outer | The outermost wrapping element. |
| wrapper | A wrapper around the label and input. |
| label | The label of the input. |
| prefix | Has output by default, but allows content directly before an input element. |
| inner | A wrapper around the actual input element. |
| suffix | Has output by default, but allows content directly after an input element. |
| input | The input element itself. |
| help | The element containing help text. |
| messages | A wrapper around all the messages. |
| message | The element (or many elements) containing a message — most often validation and error messages. |
Inputs can have their structure overridden with slots. You can precisely target where your slot content goes with section keys. Slots are then are passed the context object for use in their template.
For example, if we wanted to use a slot to define the label of an input, we could use a label slot to do so:
v-for loop to change the DOM element being used to display validation messages.FormKit provides an additional mechanism to change the structure of a FormKit input called “sections schema”. Under the hood, all FormKit inputs are powered by FormKit’s schema — a JSON compatible data format for creating and storing DOM structure and logic. This allows tremendous structural flexibility because all inputs can have pieces of their schema extended via section keys without wholesale replacement of the template.
For example, by default FormKit uses an unordered list (<ul> and <li>) to output validation messages — but perhaps you need to use <div> tags. You can change these tags using the schema prop without having to re-create any functionality:
For accessibility and flexibility, FormKit uses several wrapper elements like the ones in the wrapper and inner sections. However, perhaps on some inputs you need to remove a wrapper element to ensure other elements are adjacent. You can do this by providing a null value as the schema element:
Section schemas can also change the content being output using advanced schema logic. You could, for example, output a special value when your input’s value matches a particular string: