- Docs
- Run rules with validate()
Run rules with validate()
Runs validation against the configured validators. Returns the result and marks the form as validated.
Runs validation against the configured validators. Returns the result and marks the form as validated.
Signature
validate(): ValidationResult
validate(fields: string[]): ValidationResult
interface ValidationResult {
isValid: boolean
errors: FormErrors
}
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
fields |
string[] |
no | When provided, only the listed fields are validated. When omitted, every field with rules is validated. |
Returns
isValid—truewhen the merged error map (validation + manual) is empty.errors— the merged error map (validation + manual). The map is a fresh object — safe to mutate.
Behaviour
- Marks the form as validated (
state.isValidated = true). This means future field changes will run validation again, even when the controller was created withautoValidate: false. - Re-syncs visual attributes (
css-filled/css-error) for the affected fields. - After the form is validated, an input event also revalidates fields whose
sameAsordependsOnmetadata references the changed field. Transitive chains and cycles are deduplicated and each affected field runs once. eachvalidates every collection member independently. Item-only failures applycss-errorandaria-invalid="true"only to the failing DOM controls, while the publicerrors[field]remains a flatstring[].- Subscribers are not notified. The method updates stored errors and the
css-error/aria-invalidattributes, then returns the result: render messages from the returnederrors, or call it from a submit flow whose subscriber runs anyway. Calling it inside asubscribe()listener is safe for the same reason.
Examples
Validate the whole form
import { form } from '@samline/forms'
const signup = form('signup-form', {
validators: {
email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
password: { required: true, minLength: 8 },
},
})
const result = signup.validate()
if (!result.isValid) {
console.warn('errors:', result.errors)
}
Validate a single field
signup.validate(['email'])
Validate a sub-group of fields (e.g. a wizard step)
const wizard = form('wizard-form', {
validators: {
'step-1.name': { required: true },
'step-1.email': { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
'step-2.address': { required: true },
'step-2.city': { required: true },
},
})
function nextStep(step: 1 | 2) {
const fields = step === 1 ? ['step-1.name', 'step-1.email'] : ['step-2.address', 'step-2.city']
return wizard.validate(fields).isValid
}
Edge cases
validateignores manual errors during computation, but the returnederrorsincludes them (merged with validation errors). TheisValidflag reflects the merged map.- Validation rules must be configured via
options.validators. Fields without rules are always considered valid. - An explicit partial call validates exactly the requested fields.
validate(['password'])does not expandsameAs/dependsOnrelationships; dependency expansion happens for input events, including those dispatched bysetValue(). - Custom validators receive
{ field, value, values }. Duringeach, the context also includes the concreteelementand zero-basedindex— seeFieldValidationContext. - Numeric rules are strict and bounds are inclusive. Empty values skip
numeric,min, andmax; addrequiredwhen needed. - A custom validator that returns
falsepushes the generic message"Validation failed.". validate()is the same as callingrevalidate()` — they are aliases for readability.
Related
revalidate— alias ofvalidate.setErrorsandclearErrors— manual errors.validateValues— pure helper for use without a controller.