vue-reactive-form

A reactive form library, which can help manage form data.

It can be used in all kinds of Form UI.

Besides, It uses TypeScript generics to manage the types of data.

Warning

This is only supported in Vue3 with composition API.

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="email" 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="password"
          type="password"
          class="form-control"
        />
      </div>
      <div class="mb-3 form-check">
        <input
          id="check"
          v-model="readMe"
          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="child1" 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"
        @click.prevent="handleClick()"
      >
        Submit
      </button>
    </form>
  </div>
</template>

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

export default defineComponent({
  name: 'App',

  setup() {
    const formGroup = new FormGroup<{
      email: string
      password: string
      readMe?: boolean
      children: { child1: string }
    }>({
      email: {
        defaultValue: '[email protected]',
        validators: [requiredValidator(), emailValidator()],
      },

      password: null,
      readMe: null,
      children: { child1: null },
    })

    const {
      email,
      password,
      readMe,
      children: { child1 },
    } = formGroup.refs

    function handleClick() {
      console.log({ formGroup, values: formGroup.values.value })
    }

    return { email, password, readMe, child1, formGroup, handleClick }
  },
})

The following 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 define the input reference, which will be used in the following FormGroup.

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

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

AvailableType can also use as InputBuilder, which will stand for the defaultValue without validators.

FormBuilder

It's an Object with keys and values, and value could be the Following types.

• InputBuilder

This will create a FormControl as the control of created FormGroup.

• FormGroup

This will create a FormGroup as the control of created FormGroup.

• FormBuilder

This will use this FormGroup as the control of created FormGroup.

---

Controls

The Classes, which are used to control the form.

FormControl

The Class used to control input.

• ref

  type: Ref (Vue api)

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

• validators

type: Validator

The validator set 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 true.

• errors

  type: ComputedRef<ValidationErrors> (Vue api)

  Errors generated by failing validation, or null if there are no errors.

• valid

  type: ComputedRef<boolean> (Vue api)

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

• aware

  type: ComputedRef<boolean> (Vue api)

  It's false by default. If it's dirty and not valid, it would be 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.

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 type support for the form controls.

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

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

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

  • 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 is used to check the validity of the input.

The type of the validator is defined as the following.

You can also use ValidatorFactory

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

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

This package also provides some validator factories to create validator as the following, but you can also use your validators or validator factories.

• requiredValidator()

  error type: {required: true}

  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 matches 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