# Introduction

Vue Formulate is the easiest way to build forms using Vue.

Introducing Vue Formulate — truly delightful form authoring.

An overview of Vue Formulate by the author. Why it exists, what it does, and where it is going.

Although forms are required in almost every project developers encounter they are surprisingly tedious to create. Vue Formulate is built to increase developer happiness by anticipating pain points and exposing clean APIs — with sensible defaults — that make implementing common features effortless. In fact, there are only 2 components that need to be learned to create nearly any type of form: FormulateInput and FormulateForm.

With Vue Formulate developers are empowered to:

✓ Create any input element with a single component
✓ Use native v-model binding across all input types
✓ Re-populate an entire form from a single object
✓ Generate a form using JSON
✓ Easily add field labels
✓ Easily add help text
✓ Group fields into custom data structures
✓ Repeat grouped fields for complex UIs
✓ Perform robust form validation
✓ Create custom validation rules
✓ Modify default validation messages
✓ Create and share custom inputs
✓ Override default component templates with scoped slots
✓ And so much more

# Inputs

Every type of input in Vue Formulate is an instance of the FormulateInput component. This component is used whether you need a text input, password, select list, checkbox, or date picker. It doesn't get much easier to remember than that.

# A simple example

The simplest implementation of Vue Formulate is outputting a single FormulateInput with no additional configuration:

<FormulateInput type="text" />

Output:

Familiar right? This is essentially equivalent to the native HTML:

<input type="text">

# Outputting different input types

All Vue Formulate inputs share this same syntax. Swap out the value of type to get the desired element, even if the internal HTML structure differs. For example a <textarea> is a completely different element than <input> in HTML, but in Vue Formulate you only need to remember to change the type.

<FormulateInput type="textarea" />

Output:

TIP

With Vue Formulate you only need to use the supplied FormulateInput element and pass the appropriate type to generate the input type that you need. No need to remember a variety of component names to handle different input types.

# Validation

Input and form validation are a core feature and easy to add.

<FormulateInput
  type="email"
  name="email"
  validation="required|email"
/>

Read more about on the validation documentation page.

# Model binding

Vue Formulate uses model binding (v-model) to read/write values in and out of inputs. You can bind data on a <FormulateInput>, <FormulateForm>, or both (read the forms documentation for information on form binding).

<template>
  <div>
    <FormulateInput
      type="text"
      label="What is your name?"
      v-model="value"
    />
    <strong>Hello <em>{{ value }}</em>!</strong>
  </div>
</template>

<script>
export default {
  data () {
    return {
      value: 'My initial value'
    }
  }
}
</script>

Output:

What is your name?

Hello My initial value!

# Double binding

Because the input's value is bound to the model you can bind the model to multiple inputs, even triggering validation errors on those other elements.

<template>
  <div>
    <FormulateInput
      type="text"
      label="Favorite car brand?"
      validation="not:Toyota"
      validation-name="car brand"
      error-behavior="live"
      v-model="brand"
    />
    <FormulateInput
      type="radio"
      v-model="brand"
      error-behavior="live"
      validation="in:Toyota,Honda"
      :options="{Toyota: 'I like Toyota', Honda: 'I like Honda' }"
    />
  </div>
</template>

<script>
export default {
  data () {
    return {
      brand: 'Honda'
    }
  }
}
</script>

Output:

Favorite car brand?

I like Toyota

I like Honda

# Array binding

Certain types of inputs set an array of values on their model.

<FormulateInput
  type="checkbox"
  label="Which animals make good pets?"
  v-model="pets"
  :options="{dog: 'Dogs', alligators: 'Alligators', cat: 'Cats'}"
/>

Output:

Which animals make good pets?

Dogs

Alligators

Cats

[]

# Form binding

In addition to binding values to individual FormulateInput fields, you can also collect all the values from a collection of inputs by wrapping them in a FormulateForm and placing a v-model on that element.

<FormulateForm
  v-model="formValues"
>
  <FormulateInput
    name="name"
    label="What is your name?"
    validation="required"
  />
  <FormulateInput
    name="age"
    label="How old are you?"
    validation="required|number|max:120"
  />
  <FormulateInput
    type="submit"
    label="Sign up"
  />
</FormulateForm>

{}

# What it isn’t

While Vue Formulate is a powerful tool for building, validating, and handling errors on forms — there are some things this package does not aim to do:

This is not a UI framework or a layout tool. Want inputs next to each other? Cool! Wrap some inputs in a <div> and sprinkle on some flexbox. This package assumes you'll still be responsible for your form layout.
This package is BYOB — bring your own backend. Vue Formulate doesn't care a lick about the backend you choose (the closest it gets to caring is when using file inputs)

# Why not...?

# Vuetify

Vuetify is full UI framework while Vue Formulate is a focused tool for building forms. Some people prefer not to use large UI frameworks, don’t have them on a pre-existing project, don’t want to learn a new framework, or just prefer writing their own narrowly scoped styles. Also, we think composing forms in Vue Formulate is second-to-none.

# Buefy

Similar to Vuetify, Buefy is a full UI framework. If you’re already using Bulma or you're looking for a comprehensive UI solution it’s a solid choice. Vue Formulate is happy to live in the context of any UI framework and still offers the benefits of slick form composition, validation, and error handling to name a few. Even still there are plenty of people who don’t want or need a full UI framework that would benefit from Vue Formulate’s focused approach.

# vue-forms

The vue-forms package is focused exclusively on form validation, while Vue Formulate takes a more holistic and opinionated approach to forms and ships with UI scaffolding, validation, and data modeling. We wanted to make form composition a lot easier for developers while still increasing the overall quality — try it out.

# VeeValidate

VeeValidate is another great option for Vue form validation, and thats it’s primary mission — validation. Vue Formulate makes building high quality forms easier by including validation as a sub-feature of the field composition itself. Building forms with Vue Formulate is super easy and blazing fast — of course if you need the extra validation power, you still have it. You can write any custom validation logic you want, even on individual fields.

# Vuelidate

Yet another great option for form validation, but focused solely on validation. Vue Formulate provides additional scaffolding allowing developers to create complex forms with minimal friction with validation and error handling included.

# vue-form-generator

Generating forms from JSON is great, and also a sub-feature of Vue Formulate. Since Vue Formulate uses a single element to create any input type form generation from a JSON string or JavaScript module is as simple as using a v-for directive. Checkout the documentation.

← Installation Validation →