Validate form components
Built-in validation and error messages
Enable default validation
- Use the
requiredattribute on form components to activate required field validation. - Turn off browser validation by adding
novalidateto the form tag.
How validation works
Validation properties
validator and validate-on properties. validator | validate-on |
| -------- | ------- |
| Determines what gets validated. | Determines when the validation check will happen. |
| The form component will validate an array of functions in the order they appear. | blur: The check happens the moment a user clicks out of or tabs away from the box.submit: The check happens when the form is submitted.other: The check happens on a different event set by the developer. The developer defines this using thevalidate()method on each component.
Javascript
const gcdsComponent = document.querySelector('gcds-input');
gcdsComponent.validator = [customValidation()];React
<GcdsInput
validator={[customValidation()]}
/>Blur
<gcds-input
name="blur-validate"
label="Validate on blur"
required
validate-on="blur"
></gcds-input>Submit
<gcds-input
name="submit-validate"
label="Validate on submit"
required
validate-on="submit"
></gcds-input>Other
<gcds-input
name="other-validate"
label="Validate on other"
required
validate-on="other"
></gcds-input>Validation events
gcdsError or gcdsValid event. gcdsError | gcdsValid |
| -------- | ------- |
| The data did not pass the checks. | The data passed the checks. |
| The event will contain a detail with the associated error message. That error message will be displayed on the component. | An error message will not be displayed. | Validation objects
validate property that can be called by the form component. validate property returns an object with multiple properties for the component to read: - The
validproperty contains a boolean value stating if the passed value of the form component passes the validation test. - The
reasonproperty contains an object withenandfrproperties containing the text for the error message in each language. - The
errorsproperty is an optional property built for more complex form components with multiple form elements that contains an object with boolean properties to inform the form component which element is not valid. The need for this property in a validator will be defined when each form component is created.
// Required field validator used in gcds-input
const requiredField: Validator<string> = {
validate: (value: string) => {
return {
valid: value != null && value.trim() != '',
reason: {
en: 'Enter information to continue.',
fr: 'Saisissez des renseignements pour continuer.',
},
};
},
};Validator return
interface ValidatorReturn {
valid: boolean;
reason: {
en: string;
fr: string;
};
errors?: object;
}Validator return with errors
date-input {
valid: boolean;
reason: {
en: string;
fr: string;
};
errors: {
year: boolean;
month: boolean;
day: boolean;
}
}Customize validation and error messages
- Add custom validation using the
validatorproperty. - Change the validation event using the
validate-onproperty.
<gcds-input
input-id="form-name"
label="Name of component library"
name="library-name"
required
></gcds-input>
<script>
const input = document.querySelector('gcds-input[name="library-name"]');
const libraryName = () => {
return {
validate: value => {
return {
valid: value === '@gcds-core/components',
reason: {
en: `The entered value must be '@gcds-core/components'.`,
fr: `La valeur saisie doit être « @gcds-core/components ».`,
},
};
},
};
};
input.validator = [libraryName()];
</script>Validator format for different components
Format of the gcds-checkboxes validator:
const validator = () => {
return {
validate: value: string[] => {
return {
valid: boolean,
reason: {
en: string,
fr: string,
},
};
},
};
};
</script>Format of the gcds-date-input validator:
const validator = () => {
return {
validate: value: string => {
return {
valid: boolean,
reason: {
en: string,
fr: string,
},
errors: {
year: boolean,
month: boolean,
day: boolean,
},
};
},
};
};
</script>Format of the gcds-file-uploader validator:
const validator = () => {
return {
validate: value: FileList => {
return {
valid: boolean,
reason: {
en: string,
fr: string,
},
};
},
};
};
</script>The validation of gcds-input, gcds-select, gcds-textarea, gcds-radios follow the same pattern.
Format of the their respective validator:
const validator = () => {
return {
validate: value: string => {
return {
valid: boolean,
reason: {
en: string,
fr: string,
},
};
},
};
};
</script>