Form Validation Schema Individual Fields

Individual fields are form validation schema objects that represent the validation state of a single form input.

A form schema field is defined as an object with a value or validators field, or an empty object.

const { schema } = useForm<{ 
    username: string; 
    password: string; 
}>({
    username: {
        value: '',
        validators: [
            { name: 'required' }
        ]
    },
    password: {
        validators: [
            { name: 'required' },
            { name: 'minLength', value: 8 }
        ]
    }
});

Resolved Schema

The resolved schema object looks as follows:

{
    username: {
        value: '',
        valid: true,
        invalid: false,
        touched: false,
        untouched: true,
        dirty: false,
        pristine: true,
        errors: [],
        validators: [ ... ]
    },
    password: {
        value: '',
        valid: true,
        invalid: false,
        touched: false,
        untouched: true,
        dirty: false,
        pristine: true,
        errors: [],
        validators: [ ... ]
    },
    valid: true,
    invalid: false,
    touched: false,
    untouched: true,
    dirty: false,
    pristine: true,
    errors: []
}

Connecting Fields to Form Inputs

The field key is used to connect to the form input components using the name prop.

<script lang="ts" setup>
import { useForm } from '@inkline/inkline';
    
const { schema } = useForm<{ 
    username: string; 
    password: string; 
}>({
    username: {},
    password: {}
});
</script>

<template>
    <IForm v-model="schema">
        <IFormGroup>
            <IInput name="username" />
        </IFormGroup>
        <IFormGroup>
            <IInput name="password" type="password" />
        </IFormGroup>
    </IForm>
</template>

Initial Field Value

Providing a default initial value for a validation schema field can be done by providing a value for the value field:

<script lang="ts" setup>
import { useForm } from '@inkline/inkline/composables';

const { schema } = useForm<{
    input: string;
}>({
    input: {
        value: 'Default value'
    }
});
</script>
<template>
    <IForm v-model="schema">
        <IFormGroup>
            <IFormLabel for="input-with-default-value"> Input with default value </IFormLabel>
            <IInput id="input-with-default-value" name="input" placeholder="Type something.." />
        </IFormGroup>
    </IForm>
</template>

Validators

Validators are defined as an array of objects or strings. Each validator has specific properties that can be used to configure the validation rule.

See the list of available validators.

const { schema } = useForm<{ field: string; }>({
    username: {
        validators: [
            'required'
        ]
    },
});

const { schema } = useForm<{ field: string; }>({
    password: {
        validators: [
            'required',
            { name: 'minLength', value: 8 },
        ]
    },
});

Custom Validator Error Message

Each validator accepts a custom validation error message using the message field. This allows you to easily use i18n to display custom translated error messages.

<script lang="ts" setup>
import { useForm } from '@inkline/inkline/composables';

const { schema } = useForm<{
    input: string;
}>({
    input: {
        validators: [{ name: 'required', message: 'This field is required' }]
    }
});
</script>
<template>
    <IForm v-model="schema">
        <IFormGroup>
            <IFormLabel for="input-with-custom-error-message">
                Input with custom error message
            </IFormLabel>
            <IInput
                id="input-with-custom-error-message"
                name="input"
                placeholder="Type something.."
            />
            <IFormError for="input" />
        </IFormGroup>
    </IForm>
</template>

Validation Event

By using the validateOn field you can specify the event that triggers the validation. By default, fields get validated on both input and blur.

<script lang="ts" setup>
import { useForm } from '@inkline/inkline/composables';

const { schema } = useForm<{
    input: string;
}>({
    input: {
        validateOn: 'input',
        validators: [{ name: 'minLength', value: 5 }]
    }
});
</script>
<template>
    <IForm v-model="schema">
        <IFormGroup>
            <IFormLabel for="input-with-custom-validation-event">
                Input validated on input
            </IFormLabel>
            <IInput
                id="input-with-custom-validation-event"
                name="input"
                placeholder="Type something.."
            />
            <IFormError for="input" :visible="['invalid']" />
        </IFormGroup>
    </IForm>
</template>

The default field validation events can be configured globally when initializing Inkline or by updating the value of useInkline().options.validateOn.