vue3-form-validation

A lightweight, headless form validation library for Vue 3. Một thư viện xác thực form gọn nhẹ, không giao diện (headless) cho Vue 3.

Live demo: vue3-form-validation

Features / Tính năng

• Headless: Does not dictate your UI or styling. Works with standard HTML inputs or any custom components. / Không ép buộc giao diện. Hoạt động với thẻ HTML chuẩn hoặc component tuỳ chỉnh.
• Simple API: Only requires two components SForm and SFormItem. / API đơn giản: Chỉ cần SForm và SFormItem.
• Flexible Rules: Built-in support for async-validator-like syntax including type, required, min, max, minLength, maxLength, len, pattern, enum, and custom asynchronous validators. / Quy tắc linh hoạt: Hỗ trợ cú pháp tương tự async-validator bao gồm type, required, min, max, minLength, maxLength, len, pattern, enum và tuỳ chỉnh (async validator).

Installation / Cài đặt

npm install @mvtcode/vue3-form-validation
# or
yarn add @mvtcode/vue3-form-validation
# or
pnpm add @mvtcode/vue3-form-validation

Basic Usage / Hướng dẫn sử dụng

<script setup lang="ts">
import '@mvtcode/vue3-form-validation/style.css'
import { reactive, shallowRef } from 'vue'
import { SForm, SFormItem } from '@mvtcode/vue3-form-validation'
import type { FormRules } from '@mvtcode/vue3-form-validation'

const formRef = shallowRef<InstanceType<typeof SForm> | null>()

const form = reactive({
  username: '',
  password: '',
})

const rules: FormRules = {
  username: [
    { required: true, message: 'Username is required', trigger: 'blur' },
    { minLength: 3, maxLength: 15, message: 'Length should be 3 to 15', trigger: 'blur' },
  ],
  email: [
    { required: true, message: 'Email is required', trigger: 'blur' },
    { type: 'email', message: 'Invalid email format', trigger: ['blur', 'change'] },
  ],
  password: [
    { required: true, message: 'Password is required', trigger: 'blur' },
    { minLength: 6, message: 'Password must be at least 6 characters', trigger: 'blur' },
  ],
}

const onSubmit = async () => {
  if (!formRef.value) return
  const isValid = await formRef.value.validate()
  if (isValid) {
    alert('Success!')
  }
}
</script>

<template>
  <SForm ref="formRef" :model="form" :rules="rules" label-width="120px">
    <SFormItem label="Username" prop="username" v-slot="{ attrs, message, validateState }">
      <input type="text" v-model="form.username" v-bind="attrs" />
      <span v-if="message" style="color: red">{{ message }}</span>
    </SFormItem>

    <SFormItem label="Password" prop="password" v-slot="{ attrs, message, validateState }">
      <input type="password" v-model="form.password" v-bind="attrs" />
      <span v-if="message" style="color: red">{{ message }}</span>
    </SFormItem>

    <button type="button" @click="onSubmit">Submit</button>
  </SForm>
</template>

API Reference / Tài liệu API

SForm Props

| Prop | Type | Description | | ---------------- | --------------------------------------- | ------------------------------------------ | | model | Object (required) | Form data model. / Model dữ liệu của form. | | rules | Object (optional) | Validation rules. / Quy tắc xác thực. | | label-position | 'right' \| 'left' \| 'top' (optional) | Label text alignment. / Vị trí nhãn. | | label-width | String \| Number (optional) | Label width. / Chiều rộng nhãn. |

SForm Methods

| Method | Returns | Description | | ----------------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | | validate() | Promise<boolean> | Validates the entire form. / Xác thực toàn bộ form. | | validateField(prop: string) | Promise<boolean> | Validates a specific field. / Xác thực một trường. | | reset() | void | Resets the form to initial values and clears errors. / Đặt lại form về giá trị ban đầu và xoá lỗi. | | clearValidate() | void | Clears validation errors. / Xoá lỗi xác thực. |

SForm Events

| Event | Description | | -------- | ----------------------------------- | | submit | Emitted when the form is submitted. | | reset | Emitted when the form is reset. |

Validation Rules (RuleItem)

| Rule | Type | Description | | ------------------------- | -------------------- | -------------------------------------------------------------------------------------------- | | type | string | Type of value ('string', 'number', etc.). / Loại giá trị ('string', 'number', etc.). | | required | boolean | Field must not be empty. / Trường không được để trống. | | min / max | number | Minimum/maximum value for numbers. / Giá trị tối thiểu/tối đa cho số. | | minLength / maxLength | number | Minimum/maximum length for strings/arrays. / Độ dài tối thiểu/tối đa cho chuỗi/mảng. | | len | number | Exact length for strings/arrays. / Độ dài chính xác cho chuỗi/mảng. | | pattern | string (regex) | Regular expression that must match. / Biểu thức chính quy cần khớp. | | enum | array | Allowed values. / Giá trị cho phép. | | validator | function | Custom async validation function. / Hàm kiểm tra async tuỳ chỉnh. | | trigger | 'blur' \| 'change' | Event to trigger validation. / Sự kiện kích hoạt xác thực. | | message | string | Error message to display. / Thông báo lỗi hiển thị. |

SFormItem Props

| Prop | Type | Description | | -------------- | -------------------- | ------------------------------------------- | | prop | String (required) | Key of the model to validate. | | label | String (optional) | Label text. | | hidden-label | Boolean (optional) | Hide the label and remove its layout space. |

SFormItem Scoped Slot Props (#default)

| Prop | Type | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | attrs | object | Dynamic attributes for the input (e.g., onBlur, onInput). / Thuộc tính động cho input (vd: onBlur, onInput). | | message | string | Error message if validation fails. / Thông báo lỗi nếu xác thực thất bại. | | validateState | string | Validation state ('', 'error', 'success', 'validating'). / Trạng thái xác thực ('', 'error', 'success', 'validating'). |

SFormItem Named Slots

| Slot | Description | | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | #label | Custom label slot. Scoped props: label, value, validateState. / Slot nhãn tùy chỉnh. Props: label, value, validateState. |

👨‍💻 Author / Tác giả

Mạc Tân (Tanmv) | mvtcode

• 📧 Email: [email protected]
• 📘 FB: Mạc Tân
• ✈️ Telegram: @tanmac

📜 License

MIT License © 2026-present Mạc Tân (mvtcode). See LICENSE for details.