vue-use-form-state
v1.0.5
Published
A composable utility for encapsulating form state and validation logic in Vue applications.
Downloads
25
Readme
vue-use-form-state
A composable utility that simplifies encapsulation and managing form state and validation logic in Vue applications. It provides real-time validation feedback by reactively updating the form’s validity status when form data changes.
Key Features
- Reactive validation: The validity state automatically updates when the form data changes.
- Built-in form state management: Manage form data, errors, and warnings with a simple API.
- Customizable validation logic: Encapsulate you validation rules with a flexible validator function.
- Deep validation: Supports validation for deeply nested form data and error structures.
Basic Usage
In a form component:
import { useFormState } from 'vue-use-form-state';
const { data, errors, validate, reset } = useFormState({
initialData: {
name: '',
},
validator(data, errors, warnings) {
if (data.name.trim().length === 0) {
errors.name = 'Please enter a name';
}
if (data.name.length > NAME_MAX_LEN) {
errors.name = `Name cannot exceed ${NAME_MAX_LEN} characters`;
}
// Any other validation logic...
},
});
function handleClose() {
reset();
// Additional logic on form close...
}
function handleSubmit() {
// Validate the form before submission
if (!validate()) {
return;
}
// Proceed with form submission logic when the form is valid...
}
<MyInput
value={data.value.name}
onChange={(value) => (data.value.name = value)}
validity={errors.value.name ? 'error' : 'none'}
caption={errors.value.name && <MyErrorCaption>{errors.value.name}</MyErrorCaption>}
/>
In this example:
data
holds the form's reactive state.errors
holds the form's reactive validity state.validate()
triggers validation logic.reset()
resets the form to its initial state.
Options
initialData: Object
The starting values for your form. These values will be passed to the validator during the first call tovalidate()
.initialErrors: Object
(optional) Initial state for form errors. You can provide a default state that will be passed to the validator.initialWarnings: Object
(optional) Similar toinitialErrors
but for non-critical warning messages.validator(data, errors, warnings): Function
A custom function where you define validation logic. It runs whenvalidate()
is called and reactively updates as data changes. Use this to assign error and warning messages to specific fields.
State
data: Object
The form data being validated. Any changes to this object will trigger reactive revalidation but only aftervalidate()
is invoked at least once.errors: Object
Stores validation errors set within thevalidator
function. Access this to display error messages in your form.warnings: Object
Holds non-fatal warning messages from thevalidator
.hasErrors: Boolean
A reactive flag that indicates whether there are any errors in the form.
Methods
validate(): boolean
- Triggers the initial validation and enables reactive validation for subsequent changes todata
. Returns value ofhasErrors
described above.reset(data?: Object)
- Resets validation state, resetsdata
toinitialData
and stops reactive validation updates. Optionaldata
argument can be used to overwrite certain fields of initialData.
Note:
The validation works with deeply nested form data and error structures. It checks whether the errors
and warnings
objects contain any non-empty values after executing validator
function.
For example:
// Considered invalid and `hasErrors` will be true:
errors: {
user: {
name: 'Please enter a name'
}
}
// Considered valid and `hasErrors` will be false:
errors: {
user: {
name: '',
phoneNumbers: []
}
}