vue-reactive-form

vue-reactive-form

A reactive form library, which can help manage form data. It can be use all kind of Form UI

Install

npm i vue-reactive-form

yarn add vue-reactive-form

Usage

<template>
  <div class="container">
    <form>
      <div class="mb-3">
        <label for="email" class="form-label">Email address</label>
        <input
          id="email"
          v-model="formGroup.refs.email.value"
          type="input"
          class="form-control"
        />
        has error: {{ formGroup.controls.email.errors.value ? 'Yes' : 'No' }}
      </div>
      <div class="mb-3">
        <label for="password" class="form-label">Password</label>
        <input
          id="password"
          v-model="formGroup.refs.password.value"
          type="password"
          class="form-control"
        />
      </div>
      <div class="mb-3 form-check">
        <input
          id="check"
          v-model="formGroup.refs.readMe.value"
          type="checkbox"
          class="form-check-input"
        />
        <label class="form-check-label" for="check">remember me</label>
      </div>
      <div class="mb-3">
        <label for="child" class="form-label">child test</label>
        <input
          id="child"
          v-model="formGroup.refs.children.child1.value"
          type="input"
          class="form-control"
        />
      </div>

      <button class="btn btn-primary me-3" @click.prevent="formGroup.reset()">
        Reset
      </button>

      <button
        type="submit"
        class="btn btn-primary"
        :disabled="!formGroup.valid.value"
        @click.prevent="handleClick()"
      >
        Submit
      </button>
    </form>
  </div>
</template>

import { defineComponent } from 'vue'
import FormGroup, { emailValidator, requiredValidator } from 'vue-reactive-form'

export default defineComponent({
  name: 'App',

  setup() {
    const formGroup = new FormGroup({
      email: {
        type: 'string',
        defaultValue: '[e-mail]',
        validators: [requiredValidator(), emailValidator()],
      },

      password: { type: 'string' },
      readMe: { type: 'boolean' },
      children: new FormGroup({ child1: {} }),
    })

    function handleClick() {
      console.log(formGroup)
    }

    return { formGroup, handleClick }
  },
})
</script>

The fallowing is the demo of this code.

Demo

Demo

PS. I use Bootstrap CDN for this demo page. However, It's not required to use with this "vue-reactive-form" package.

API

Builder

---

InputBuilder

This is used to defined the input reference, which will be used in the fallowing FormGroup.

Property	type	required	default	description
type	AvailableStringType	false	'any'	defining type
defaultValue	AvailableType	false	null	default value
validators	Validator[]	false	[]	Validators for the input, there are details in the fallowing

type AvailableStringType =
  | 'boolean'
  | 'number'
  | 'string'
  | 'boolean[]'
  | 'number[]'
  | 'string[]'
  | 'any'

type AvailableType =
  | boolean
  | number
  | string
  | boolean[]
  | number[]
  | string[]
  | any

FormBuilder

It's a Object with keys and values, and value could be the Fallowing types.

• InputBuilder
• FormGroup
• DynamicFormGroup

If value is a InputBuilder, it will create a FormControl.

---

Controls

The Classes, which are used to control the form.

FormControl

The Class used to control a input.

• ref

  type : Ref (Vue api)

  Vue refs api, which can be used in V-model.

• validators

type : Validator

The validator setted in the InputBuilder, used to check the input validity.

• dirty

type : Ref<boolean> (Vue api)

It's false by default, after changing the value of the ref it would be marked as true

• errors

  type : ComputedRef<ValidationErrors> (Vue api)

  It's null by default, after changing the value of the ref it would be marked as the error setted in the validators.

• valid

  type : ComputedRef<boolean> (Vue api)

  It's false by default, if it's dirty and the error is null, it would be marked as true.

• markAsDirty()

  return : void

  Mark the property dirty as true.

• markAsPristine()

  return : void

  Mark the property dirty as false.

• appendValidators(validator)

  args : Validator

  return : void

  Append the validator to the validators.

• setValidators(validators)

  args : Validator | Validator[]

  return : void

  Set the validators.

• clearValidators()

  return : void

  Clear the validators.

• reset()

  return : void

  Reset the value, dirty and the errors.

AbstractFormGroup

This is a abstract form group class, It's the prototype of FormGroup and DynamicFormGroup.

It's can't be used directly.

However, it's shared some properties and methods with FormGroup and DynamicFormGroup.

• dirty

  type : Ref<boolean> (Vue api)

  It's false by default, after changing any form control value it would be marked as true.

• errors

  type : ComputedRef<FormErrors<T>>

  It's an assembly of all the errors of the form controls. If there is no error, it would be null.

• valid

  type : ComputedRef<boolean> (Vue api)

  It's false by default, if it's dirty and the error is null, it would be marked as true.

• markAsDirty()

  return : void

  Mark the properties dirty in all the form controls as true.

• markAsPristine()

  return : void

  Mark the properties dirty in all the form controls as false.

• reset()

  return : void

  Reset the value, dirty and the errors of all the form controls.

FormGroup

The main class of this package. It's used to create a form group with not only inputs but also other form groups.

It's also the default export of this package.

To create a form group, you can use FormBuilder object.

TypeScript generics is used to define the mapped types of the form controls.

The generic Type variables "T" is the type of the FormBuilder used to create the form group.

• controls

  type : FormControls<T>

  It's an assembly of all the form controls or form groups.

• refs

  type : FormRefs<T>

  It's an assembly of all the refs of the form controls or form groups.

  It can be used in the V-model.

DynamicFormGroup

This is very similar with FormGroup, but it's used to create a form group with dynamic form controls.

All the properties and methods of FormGroup are also available.

However, since it's dynamic, TypeScript generics is not used to define the mapped types of the form controls.

• appendFormControl(formBuilder)

  args : FormBuilder

  return : void

  Append a group of form controls to the form group.

• removeFormControl(key)

  args : string | string[]

  return : void

  Remove one or more form controls from the form group by the key of the property.

---

Validator

The function used to check the validity of the input.

Type of the validator is Validator, which is defined as the fallowing.

You can also use ValidatorFactory

export type ValidationErrors = {
  [key: string]: any
}

export type Validator = (value: AvailableType) => ValidationErrors | null

This package also provide some validator factories to create validator as the fallowing, but you can also use your own validators or validator factories.

• requiredValidator()

  error type: {required: true}

  It's used to check if the input has a value.

• emailValidator()

  error type: {email: 'email'}

  It's to check if the value is an email.

• patternValidator(regex)

  args : RegExp | string

  error type: {pattern: 'pattern'}

  It's to check if the value is match the regex.

• maxLengthValidator(maxLength)

  args : number

  error type: {maxLength: number}

  It's to check if the value is less than the maxLength.

• maxLengthValidator(minLength)

  args : number

  error type: {minLength: number}

  It's to check if the value is greater than the minLength.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT © ronny1020