Nucleus Powered Mitochondria

    vue-final-form

    3.0.1 • Public • Published

    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 slot-scope="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 slot-scope="props" @submit="props.handleSubmit">
        <FinalField
          name="username"
          :validate="v => v ? null : 'this is required'">
          <div slot-scope="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:

    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:

    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

    Keywords

    none

    Install

    npm i vue-final-form

    DownloadsWeekly Downloads

    430

    Version

    3.0.1

    License

    MIT

    Unpacked Size

    28.6 kB

    Total Files

    6

    Last publish

    Collaborators

    • rem
    • xbrain