API Reference

useForm()

import type { ComputedRef, UnwrapRef } from 'vue';
import { Plugin } from './plugins';
import { Field } from './useField';
import { AsyncValidator, Validator } from './validators';
export interface Form<T extends {} = any> {
    values: UnwrapRef<Values<T>>;
    fields: UnwrapRef<Fields<T>>;
    /**
     * State
     */
    valid: boolean;
    invalid: boolean;
    enabled: boolean;
    disabled: boolean;
    pristine: boolean;
    dirty: boolean;
    untouched: boolean;
    touched: boolean;
    pending: boolean;
    submitted: boolean;
    validators: Set<Validator<UnwrappedValues<T>>>;
    asyncValidators: Set<AsyncValidator<UnwrappedValues<T>>>;
    errors: string[];
    setValues: (values: Partial<{
        [Key in keyof T]: T[Key];
    }>) => void;
    reset: () => void;
    disable: () => void;
    enable: () => void;
    awaitValidation: () => Promise<void>;
    addPlugin: (plugin: Plugin) => void;
}
export type Values<T> = {
    [Key in keyof T]: T[Key] extends object ? Values<T[Key]> : ComputedRef<T[Key] | undefined>;
};
export type UnwrappedValues<T> = UnwrapRef<Values<T>>;
export type Fields<T> = {
    [Key in keyof T]: T[Key] extends object ? Form<T[Key]> : Field<T[Key]>;
};
export type FieldOptions<T> = {
    [Key in keyof T]: [initialValue: T[Key], validators?: Validator[], asyncValidators?: AsyncValidator[]] | {
        [Key2 in keyof T[Key]]: [
            initialValue: T[Key][Key2],
            validators?: Validator[],
            asyncValidators?: AsyncValidator[]
        ] | {
            [Key3 in keyof T[Key][Key2]]: [
                initialValue: T[Key][Key2][Key3],
                validators?: Validator[],
                asyncValidators?: AsyncValidator[]
            ];
        };
    };
};
export type UseFormOptions<T> = {
    plugins?: Plugin[];
    validators?: Validator<UnwrappedValues<T>>[];
    asyncValidators?: AsyncValidator<UnwrappedValues<T>>[];
};
export declare function useForm<T extends {}>(fieldOptions: FieldOptions<T>, options?: UseFormOptions<T>): Form<T>;

Form

export interface Form<T extends {} = any> {
	values: UnwrapRef<Values<T>>;
	fields: UnwrapRef<Fields<T>>;

	/**
	 * State
	 */
	valid: boolean;
	invalid: boolean;
	enabled: boolean;
	disabled: boolean;
	pristine: boolean;
	dirty: boolean;
	untouched: boolean;
	touched: boolean;
	pending: boolean;
	submitted: boolean;

	// Validators and errors
	validators: Set<Validator<UnwrappedValues<T>>>;
	asyncValidators: Set<AsyncValidator<UnwrappedValues<T>>>;
	errors: string[];

	// functions
	setValues: (values: Partial<{ [Key in keyof T]: T[Key] }>) => void;
	reset: () => void;
	disable: () => void;
	enable: () => void;
	awaitValidation: () => Promise<void>;
	addPlugin: (plugin: Plugin) => void;
}

FieldOptions

export type FieldOptions<T> = {
	[Key in keyof T]:
		| [initialValue: T[Key], validators?: Validator[], asyncValidators?: AsyncValidator[]]
		| {
				[Key2 in keyof T[Key]]:
					| [
							initialValue: T[Key][Key2],
							validators?: Validator[],
							asyncValidators?: AsyncValidator[],
					  ]
					| {
							[Key3 in keyof T[Key][Key2]]: [
								initialValue: T[Key][Key2][Key3],
								validators?: Validator[],
								asyncValidators?: AsyncValidator[],
							];
					  };
		  };
};

UseFormOptions

export type UseFormOptions<T> = {
	plugins?: Plugin[];
	validators?: Validator<UnwrappedValues<T>>[];
	asyncValidators?: AsyncValidator<UnwrappedValues<T>>[];
};

useField()

import { AsyncValidator, Validator } from './validators';
export interface UseFieldOptions {
    validators?: Validator[];
    asyncValidators?: AsyncValidator[];
}
export interface Field<T = any> {
    value: T;
    valid: boolean;
    invalid: boolean;
    enabled: boolean;
    disabled: boolean;
    pristine: boolean;
    dirty: boolean;
    async: boolean;
    untouched: boolean;
    touched: boolean;
    pending: boolean;
    validators: Set<Validator>;
    asyncValidators: Set<AsyncValidator>;
    errors: string[];
    reset: () => void;
    disable: () => void;
    enable: () => void;
    awaitValidation: () => Promise<void>;
}
export declare function useField<T>(initialValue: T, options?: UseFieldOptions): Field<T>;

Field

export interface Field<T = any> {
	// v-model value
	value: T;

	// state
	valid: boolean;
	invalid: boolean;
	enabled: boolean;
	disabled: boolean;
	pristine: boolean;
	dirty: boolean;
	async: boolean;
	untouched: boolean;
	touched: boolean;
	pending: boolean;

	// Validators and errors
	validators: Set<Validator>;
	asyncValidators: Set<AsyncValidator>;
	errors: string[];

	// functions
	reset: () => void;
	disable: () => void;
	enable: () => void;
	awaitValidation: () => Promise<void>;
}

definePlugin()

import { Form } from '../useForm';
export * from './storagePlugin';
export type Plugin<TForm extends Form = Form> = (form: TForm) => void;
export type PluginFactory<TForm extends Form = Form> = (...params: any) => Plugin<TForm>;
export declare function definePlugin<TArgs = undefined, TForm extends Form = Form>(fn: (form: TForm, args: TArgs) => void): PluginFactory<TForm>;

Validator

export type Validator<TValue = unknown> = {
	name: string;
	args?: any;
	validate: (value: TValue) => boolean;
};

AsyncValidator

export type AsyncValidator<TValue = unknown> = {
	name: string;
	args?: any;
	validate: (value: TValue) => Promise<boolean>;
};