Forms and Fields

useForm is pretty much at the core of @vuetils/form. Every time you want to group two or more input elements together useForm is probably the way to go. If on the other hand you are dealing with just a single input you can use useField.

UseForm

useForm groups together multible form fields and exposes a couple of properties and functions to interact with the form and its fields. Internaly useForm uses useField to create a Field instance for every form field.

Usage

Define a form with useForm passing an object describing your form layout. Every property of the object represents an input element in your form. The key of the property corresponds to the name attribute of an input element and the value is an array where the first element is the initial value of the input, the second element is an array of validators and the third element is an array of async valdiators.

import { defineValidator, useForm } from '@vuetils/form';

const syncValidator = defineValidator('sync', (value) => true);
const asyncValidator = defineValidator('async', async (value) => true);

const form = useForm({
	hallo: ['initialValue', [syncValidator], [asyncValidator]],
	zwallo: [0],
	drallo: [false, [], [asyncValidator]],
});

State

The Form instance exposes a couple of boolean properties that describe the state of the form.

• valid - true if all associated fields are valid
• invalid - opposite of valid
• enabled - true if all associated fields are enabled
• disabled - opposite of enabled
• pristine - true if all of the associated fields are pristine
• dirty - opposite of pristine
• pending - true if at least one of the associated fields is pending
• submitted - true if the form has been submitted

These properties can be acces directly on the Form instance like so:

import { useForm } from '@vuetils/form';

const form = useForm({
	hallo: [''],
});

console.log(form.pristine); // true
console.log(form.dirty); // false
console.log(form.pending); // false

Values

form.values is an object containing the values of all ascociated Field instances of a form.

import { useForm } from '@vuetils/form';

const form = useForm({
	hallo: ['hallo'],
	zwallo: [12],
	drallo: [true],
});

console.log(form.values);
// {
//   hallo: 'hallo',
//   zwallo: 12,
//   drallo: true,
// }

Fields

form.fields is an object containing all ascociated Field instances of a form.

import { useForm } from '@vuetils/form';

const form = useForm({
	hallo: [''],
	zwallo: [0],
	drallo: [false],
});

console.log(form.fields);
// {
//   hallo: Field<string>,
//   zwallo: Field<number>,
//   drallo: Field<boolean>,
// }

setValues()

form.setValues() is a type safe way to set multible values of your form at once. You have autocomplete and get errors when you want to for example set a string input to a number.

import { useForm } from '@vuetils/form';

const form = useForm({
	hallo: [''],
	zwallo: [''],
	drallo: [''],
});

form.setValues({
	hallo: 'hallo',
	zwallo: 'zwallo',
	drallo: true, // Error: Type 'boolean' is not assignable to type 'string'.
});

reset()

form.reset() resets the form state and the state of every associated field to its initial value.

import { useForm } from '@vuetils/form';

const form = useForm({ hallo: [''] });

form.reset();

disable() / enable()

form.disable() and form.enable() disables and enables all associated form fields. When used in combination with UForm or UField the disabled attribute on the input element will also be set.

import { useForm } from '@vuetils/form';

const form = useForm({ hallo: [''] });

form.disable();
form.enable();

awaitValidation()

form.awaitValidation() lets you await all pending async validators from associated form fields. The usual use case for this would be to await all the pending validation before handeling the submit event.

import { useForm } from '@vuetils/form';

const form = useForm({ hallo: [''] });

async function onSubmit() {
	await form.awaitValidation();
	if (form.isValid) throw new Error('Form is not valid');
	// do submit stuff
}

addPlugin()

With form.addPlugin() you can add plugins to a form after it has been initialized.

import { localStoragePlugin, useForm } from '@vuetils/form';

const form = useForm({ hallo: [''] });

form.addPlugin(localStoragePlugin);

UseField

With useField you can define a single form field and similary to useForm it exposes a couple of properties and functions to interact with the field.

Usage

Define a field with useField, pass an initial value and add sync or async validators.

import { defineValidator, useField } from '@vuetils/form';

const syncValidator = defineValidator('sync', (value) => true);
const asyncValidator = defineValidator('async', async (value) => true);

const field = useField('initialValue', {
	validators: [syncValidator],
	asyncValidators: [asyncValidator],
});

State

The Field instance exposes a couple of boolean properties that describe the state of the field.

• valid - true if the field is valid

• invalid - opposite of valid

• enabled - true if the field is enabled

• disabled - opposite of enabled

• pristine - true if the field is pristine

• dirty - opposite of pristine

• async - true if field has at least one async validator

• pending - true if at least on async validator is pending

  These properties can be acces directly on the Field instance like so:

import { useField } from '@vuetils/form';

const form = useField('');

console.log(form.pristine); // true
console.log(form.dirty); // false
console.log(form.pending); // false

reset()

field.reset() resets the field state to its initial value.

import { useField } from '@vuetils/form';

const field = useField('');

field.reset();

disable() / enable()

field.disable() and field.enable() disables and enables the field. When used in combination with UField the disabled attribute on the input element will also be set.

import { useField } from '@vuetils/form';

const field = useField('');

field.disable();
field.enable();

awaitValidation()

field.awaitValidation() lets you await all pending async validators.

import { useField } from '@vuetils/form';

const field = useField('');

await field.awaitValidation();