Theme

Docs Navigation

Inputs

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:

Load Live Example

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.

Setting values

There are 4 ways to set the value of an input:

  • Using the value prop.
  • Using v-model.
  • Using FormKit's node node.input() method.
  • Setting the value of a parent FormKit component.

Using value prop

You can set the value of a single input or a group of inputs using the value prop.

Load Live Example
warning
The 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.

Using v-model

Using v-model allows for two-way reactive data binding with any FormKit input.

Load Live Example
warning
The initial value of your v-model cannot be undefined. If it is, the v-model will not be used. All other values, including null and false are acceptable.

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

Load Live Example
tip
Calls to 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.

Using a parent

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.

Load Live Example

Setting attributes

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:

Load Live Example

Validation

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:

Load Live Example
Learn more about validation rules Read the docs

Debouncing

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 get the group's value from the #default slot prop and observe how it is not updated until after our 1000ms delay:

Load Live Example
Group & List delay
The delay prop’s default is 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.

Explicit errors

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.

Load Live Example
Non blocking
Explicitly set errors are non-blocking, meaning they do not prevent the form from submitting the way validation errors do. You can read more about error handling on the form documentation.

Props & attributes

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
configObject{}Configuration options to provide to the input’s node and any descendent node of this input.
delayNumber20Number of milliseconds to debounce an input’s value before the commit hook is dispatched.
errorsArray[]Array of strings to show as error messages on this field.
helpString''Text for help text associated with the input.
idStringinput_{n}The unique id of the input. Providing an id also allows the input’s node to be globally accessed.
ignoreBooleanfalsePrevents an input from being included in any parent (group, list, form etc). Useful when using inputs for UI instead of actual values.
indexNumberundefinedAllows 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.
labelString''Text for the label element associated with the input.
nameStringinput_{n}The name of the input as identified in the data object. This should be unique within a group of fields.
parentFormKitNodecontextualBy default the parent is a wrapping group, list or form — but this props allows explicit assignment of the parent node.
prefix-iconString''Specifies an icon to put in the prefixIcon section.
preservebooleanfalsePreserves the value of the input on a parent group, list, or form when the input unmounts.
preserve-errorsbooleanfalseBy 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-schemaObject{}An object of section keys and schema partial values, where each schema partial is applied to the respective section.
suffix-iconString''Specifies an icon to put in the suffixIcon section.
typeStringtextThe type of input to render from the library.
validationString, Array[]The validation rules to be applied to the input.
validation-visibilityStringblurDetermines when to show an input's failing validation rules. Valid values are blur, dirty, and live.
validation-labelString{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-rulesObject{}Additional custom validation rules to make available to the validation prop.

Events

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
inputanyEmitted when the core node’s commit hook is completed. Has it’s own debounce to reduce noise. Includes the core node as the second argument.
input-rawanyEmitted on every core node’s commit hook. Includes the core node as the second argument.
nodeFormKitNodeEmitted when the component’s setup is complete. This is the internal FormKitNode object at the heart of the input.
Vue events
The above are Vue events emitted by @formkit/vue. @formkit/core also emits its own events as part of the lifecycle of core nodes.

Sections

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
outerThe outermost wrapping element.
wrapperA wrapper around the label and input.
labelThe label of the input.
prefixHas no output by default, but allows content directly before an input element.
prefixIconAn element for outputting an icon before the prefix section.
innerA wrapper around the actual input element.
suffixHas no output by default, but allows content directly after an input element.
suffixIconAn element for outputting an icon after the suffix section.
inputThe input element itself.
helpThe element containing help text.
messagesA wrapper around all the messages.
messageThe element (or many elements) containing a message — most often validation and error messages.

Restructure markup

At times you may find it necessary to restructure the HTML inside a FormKit input, such as adding, editing, moving, or removing sections. This can be done by exporting the input (using the CLI tool), making the desired changes, and then using the modified input in your project. Read the guide on exporting inputs to learn how.

Learn to restructure your inputs Export inputs docs

Slots

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:

Load Live Example
Consider section schema
A disadvantage of using slots is you often need to re-create unrelated features to make the change you desire. For example, using slots would require you to re-implement any classes applied to those sections (which can be done by using context.classes.sectionName).

To help address this shortcoming, FormKit is also able to selectively override/extend the underlying schema of each section allowing complex structural modification often with no loss of functionality.

Sections schema

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.

Changing HTML tags

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:

Load Live Example

Unwrapping or removing HTML tags

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:

Load Live Example

Schema logic

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:

Load Live Example
Learn more about how schemas work Gimme more schema