Matador Jobs uses a built-in validation system powered by JustValidate to ensure application forms are completed correctly before submission.
In some cases, you may want to modify validation rules dynamically — for example:
Require a phone number only when an email address has not been provided.
This guide shows two supported ways to extend the validator safely from your theme or custom scripts.
When would I use this?
Common use cases include:
- Making a field conditionally required
- Changing validation rules based on another field’s value
- Removing validation when a field is no longer relevant
- Adding custom validation logic
Two Ways to Access the Validator
Matador provides two patterns for interacting with the validator:
| Pattern | When to use |
|---|---|
| Pattern A — Event-based | Best for initial setup |
| Pattern B — Direct access | Useful inside event callbacks |
Pattern A — Event-Based
The matador:validatorReady event fires once the form has been fully initialised and the validator is ready.
This is the safest and preferred way to register validation logic.
Example: Require phone number if email is empty
( function() {
document.addEventListener( "DOMContentLoaded", function() {
const form = document.querySelector( "#matador-application-form" );
if ( ! form ) {
return;
}
form.addEventListener( "matador:validatorReady", function( e ) {
const validator = e.detail.validator;
const emailInput = form.querySelector( "#email" );
const phoneInput = form.querySelector( "#phone" );
if ( ! emailInput || ! phoneInput ) {
return;
}
function updatePhoneRule() {
if ( ! emailInput.value.trim() ) {
// Require phone when email is empty
validator.addField( phoneInput, [
{ rule: "required", errorMessage: "Please provide a phone number if no email is entered." }
]);
} else {
// Remove requirement if email is filled
validator.removeField( phoneInput );
}
}
// Set initial state
updatePhoneRule();
// Update when email changes
emailInput.addEventListener( "input", updatePhoneRule );
});
});
}() );
Pattern B — Direct Access
You can also access the validator directly via:
form._justValidate
This is useful inside event handlers that run after the form has loaded.
Example: Toggle phone requirement manually
form.querySelector( "#email" )?.addEventListener( "input", function() {
const validator = form._justValidate;
if ( ! validator ) {
return;
}
const phoneInput = form.querySelector( "#phone" );
if ( ! this.value.trim() ) {
validator.addField( phoneInput, [
{ rule: "required", errorMessage: "Phone is required when email is empty." }
]);
} else {
validator.removeField( phoneInput );
}
});
Important Notes
1. addField() replaces existing rules
Calling:
validator.addField( element, rules );
will overwrite any previous validation rules for that field.
2. removeField() clears errors too
validator.removeField( element );
- Removes validation rules
- Clears any visible error messages for that field
3. Event-based vs direct access
- Use Pattern A for setup
- Use Pattern B for interaction-based updates
4. Built on JustValidate
Matador uses JustValidate under the hood.
You can:
- Use all built-in validation rules
- Define custom validators
- Combine multiple rules per field
Refer to the JustValidate documentation for:
- Available rules
- Custom validation functions
- Advanced configuration options