Inputs

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 type="text" /><FormKit type="textarea" />

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.

<FormKit type="repeater" label="My Movies" add-label="Add Movie">  <FormKit    name="movie"    type="autocomplete"    label="Search for a movie"    placeholder="Ex: Interstellar"    :options="searchMovies"  />  <FormKit type="rating" label="My rating" /></FormKit>

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.

<FormKit  label="Username"  type="text"  help="Pick a new username"  validation="required|matches:/^@[a-zA-Z]+$/|length:5"  value="@FormKit"/>

Using v-model

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

<script setup>import { ref } from 'vue'const city = ref('Florence')const cities = ref([  'Prague',  'Rome',  'Berlin',  'Amsterdam',  'Barcelona',  'London',])function randomCity() {  const index = Math.floor(Math.random() * (cities.value.length - 1))  if (cities.value[index] !== city.value) {    city.value = cities.value[index]  } else {    randomCity()  }}</script><template>  <FormKit    type="text"    label="European city"    help="What is your favorite European city?"    v-model="city"  />  <FormKit type="button" @click="randomCity">Random City</FormKit>  <pre>City: {{ city }}</pre></template>

City: Florence

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

<script setup>import { onMounted } from 'vue'import { getNode } from '@formkit/core'onMounted(() => {  const node = getNode('coffee')  let index = 0  const coffee = ['Latte', 'Americano', 'Doppio', 'Allongé', 'Macchiato']  setInterval(() => {    node.input(coffee[index])    if (index < coffee.length - 1) index++    else index = 0  }, 250)})</script><template>  <FormKit    label="Favorite type of coffee type?"    id="coffee"    help="What is your favorite type of coffee?"  /></template>

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.

<template>  <FormKit    type="group"    name="address"    :value="{      street: '456 Mangrove St',      city: 'Franklin',      state: 'ny'    }"  >    <FormKit      label="Street"      name="street"    />    <FormKit      name="city"      label="City"    />    <FormKit      type="select"      name="state"      label="State"      :options="{        ca: 'California',        ny: 'New York',        va: 'Virginia'      }"    />  </FormKit></template>

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:

<FormKit  type="text"  label="Favorite flavor"  data-category="pizza"/>

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:

<FormKit  type="text"  label="Username"  validation="required|alpha|length:10"/><!-- The input above has 3 validation rules:    "required", "alpha", and "length" -->

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:

<template>  <FormKit type="group" #default="{ value }">    <FormKit      name="email"      type="email"      label="Email"      help="Notice it takes a full second for the data to update."      :delay="1000"      validation="required|length:5|email"      validation-visibility="live"    />    <pre wrap>{{ value }}</pre>  </FormKit></template>

{}

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.

<script setup>import { ref, computed } from 'vue'const fruit = ref('')const errors = computed(() => {  return fruit.value ? [`Sorry, we are sold out of ${fruit.value}`] : []})</script><template>  <FormKit    type="select"    label="Fruit"    placeholder="Select a fruit"    v-model="fruit"    :options="['Apple', 'Peach', 'Pear']"    :errors="errors"  /></template>

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:

<script setup>const airlines = {  american: 'American Airlines',  delta: 'Delta',  easyjet: 'easyJet',  jetblue: 'JetBlue',  klm: 'KLM',  lufthansa: 'Lufthansa',}</script><template>  <FormKit    label="Airlines"    help="Which airlines do you prefer to fly on?"    type="checkbox"    :options="airlines"    option-class="!mb-0"  >    <template #label="context">      <img        :src="`https://cdn.formk.it/example-assets/airlines/${context.option.value}.png`"        width="120"        :alt="context.option.label"      />    </template>  </FormKit></template>

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:

<FormKit  label="Full name"  help="Please provide your full name."  :sections-schema="{    messages: { $el: 'div' },    message: { $el: 'span' },  }"  validation="required|length:5"  validation-visibility="live"/><!-- Remove the :sections-schema prop to see validation      messages revert to their default HTML. -->

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:

<FormKit  type="checkbox"  :sections-schema="{    outer: { $el: null },    inner: { $el: null },    messages: { $el: null },    message: { $el: 'div' },  }"  validation="+accepted"  validation-visibility="live"  label="Terms and conditions"  help="Do you accept our terms and conditions?"/><!-- Remove the "inner" property of the schema object    and see the inner wrapper reappear. -->

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:

<FormKit  type="text"  label="Your name"  help="Try entering the name “formkit”."  :sections-schema="{    label: {      children: [        '$label',        {          if: '$value == formkit',          then: {            $el: 'span',            attrs: {              style: { color: 'green' },            },            children: [              {                $el: 'span',                children: 'That\'s our name too!',                attrs: {                  class: 'ml-2',                },              },            ],          },        },      ],    },  }"  validation-visibility="live"/>