vue-final-form

Subscription-based form state management for Vue.js

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
vue-final-form
4.0.12 years ago6 years agoMinified + gzip package size for vue-final-form in KB

Readme

vue-final-form

NPM version NPM downloads CircleCI donate chat

Introduction

🏁 High performance subscription-based form state management for Vue.js.

Install

yarn add final-form vue-final-form

Usage

Edit example
This library exports two components:
import { FinalForm, FinalField } from "vue-final-form";

The first component you'll need is the FinalForm component:
<FinalForm :submit="submit">
  <!-- ignore the children for now -->
</FinalForm>

The only required prop is submit, it defines how to submit the form data, maybe simply log it:
function submit(values) {
  console.log(values);
}

The rendered output is:
<div></div>

As you can see it does nothing for now, you need to feed it a <form>:
<FinalForm :submit="submit">
  <form v-slot="props" @submit="props.handleSubmit">
    <!-- ignore the children for now -->
  </form>
</FinalForm>

Now it renders:
<div><form></form></div>

Here it uses the scoped slots feature from Vue.js (>=2.1.0), props.handleSubmit is the actual method it will run to submit data.
Next let's define a form field with <FinalField> component:
<FinalForm :submit="submit">
  <form v-slot="props" @submit="props.handleSubmit">
    <FinalField
      name="username"
      :validate="v => v ? null : 'this is required'">
      <div v-slot="props">
        <input v-on="props.events" :name="props.name">
        <span v-if="props.meta.error && props.meta.touched">
          {{ props.meta.error }}
        </span>
      </div>
    </FinalField>
  </form>
</FinalForm>

Things got a bit more complex, but it's easy if you try to understand:
The only prop that is required by FinalField is name, it tells the field where to store the field data in the form state, here we stores it as state.username.
The validate prop is used to validate the field data, it could be a function that returns an error message or null, undefined when it's considered valid.
The data that FinalField passed to its children contains props.events which is required to be bound with the input element in order to properly track events. And props.name is the name you gave FinalField, props.meta is some infomation about this field.

API

<FinalForm>

Props

submit
Type: function
Default: () => {}
Here we allow submit to be optional since you may not need it when you just use vue-final-form as a form validation tool.
See onSubmit.
validate
Type: function Array<function>
A whole-record validation function that takes all the values of the form and returns any validation errors.
See validate.
initialValues
Type: object
See initialValues.
subscription
Type: FormSubscription
Default: All
See FormSubscription.

Events

change
Params:
  • formState: https://github.com/final-form/final-form#formstate

Scoped slot props

It basically exposes everything in FormState plus follwoings:
handleSubmit
Type: function
The function that you will invoke to submit the form data, you may use it as the :submit event handler on your <form>.
reset
Type: function
See FormApi.reset.
mutators
Type: ?{ [string]: Function }
See FormApi.mutators.
batch
Type: function
See FormApi.batch.
blur
Type: function
See FormApi.blur.
change
Type: function
See FormApi.change.
focus
Type: function
See FormApi.focus
initialize
Type: function
See FormApi.initialize.

<FinalField>

Props

name
Type: string
Required: true
The name of this field.
See name.
validate
Type: function Array<function>
A field-level validation function to validate a single field value. Returns an error if the value is not valid, or undefined if the value is valid.
See validate.
subscription
Type: FieldSubscription
Default: All
See FieldSubcription.

Events

change
Params:
  • fieldState: https://github.com/final-form/final-form#fieldstate

Scoped slot props

It basically exposes FieldState.
name
Type: string
The name of this field.
See FieldState.name
change
Type: function
See FieldState.change
value
Type: any.
The current value of this field. You should probably bind it to :value of input or textarea if you have set initial value for the field.
events
Type: { input: Function, focus: Function, blur: Function }
Bind these event handlers to your input textarea element.
See FieldState.change, FieldState.focus, FieldState.blur.
meta
Type: object
Everything in FieldState except for blur change focus name

Contributing

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request :D

Author

vue-final-form © EGOIST, Released under the MIT License.
Authored and maintained by EGOIST with help from contributors (list).
egoist.moe · GitHub @EGOIST · Twitter @\_egoistlily