Inputs

• Introduction
• The Form Input
• Setting values
  • Using value prop
  • Using v-model
  • Using node.input()
  • Using a parent
• Setting attributes
• Validation
• Debouncing
• Explicit errors
• Props & attributes
• Events
• Sections
• Restructure markup
• Slots
• Sections schema
  • Changing HTML tags
  • Unwrapping or removing HTML tags
  • Schema logic
  • Learn more about schema

Introduction

FormKit 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. Our seperate FormKit Pro package provides access to "synthetic" input types such as repeater, autocomplete, mask, rating and more. Of course, you can write your own inputs too by creating custom inputs.

The Form Input

While you’re free to use FormKit inputs by themselves, you’ll usually want to group them into a form:

<FormKit type="form">
  <!-- ... your form inputs -->
</FormKit>

The form type provides a host of features including value collection, initial value setting, form submission, error handling, loading states, and more.

Setting values

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

• Using the value prop (Note: only sets initial value).
• 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 initial value of a single input or a group of inputs using the value prop.

Using v-model

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

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

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.

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:

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:

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:

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.

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.

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.

Sections

Inputs are composed of chunks of HTML called "sections". Each section has a "key" that can be used to target the section for a variety of purposes, like:

• Modifying the section's classes via {section-key}-class="your-class" props
• Overriding the section's structure with slots: <template #{section-key}>
• 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:

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.

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:

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:

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:

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:

Learn more about schema