This allows for more targeted styling and placement of the main error message per form. You can disable the display of this main error message entirely by setting the showMainError option to false.

For individual input errors, it is recommended to create an error message element (likely a div) with a unique id and then use its id in an aria-describedby attribute in each associated input. This will ensure that Validator knows exactly what error element is associated with each input, and this works seamlessly for groups of inputs, like radio buttons. This will also confer improved accessibility and allow screen readers to announce the error message when the input is focused.

If you do not use aria-describedby, Validator will fall back to displaying error messages in the first element having the id or name of the input + -error. For example, if the input id is inputid, the error message will be displayed in the div with the id inputid-error.

It is recommended to initially hide error elements with a class that sets properties such as display: none;, visibility: hidden;, or opacity: 0;.

You can customize the class(es) that Validator uses to hide the error messages by passing in a hiddenClasses option to the Validator constructor. The default is hidden opacity-0.

Color Picker Support

Use data-type="color" and the input must contain any valid CSS color supported by the browser. To use this with a native color input, add an input with type="color" and the ID of the data-color input + -color. This should be inside a linked label, which will become the color preview swatch. Such a label should have an ID of the color input's name + -color-label so that Validator can change the background to the specified color.

A basic example that would work:

`html


- messages - An object containing custom error messages. The default messages can be overridden by passing in a custom message object. These are all the default messages:

`javascript
messages = {
ERROR_MAIN: 'There is a problem with your submission.',
ERROR_GENERIC: 'Enter a valid value.',
ERROR_REQUIRED: 'This field is required.',
OPTION_REQUIRED: 'An option must be selected.',
CHECKED_REQUIRED: 'This must be checked.',
ERROR_MAXLENGTH: 'This must be ${val} characters or fewer.',
ERROR_MINLENGTH: 'This must be at least ${val} characters.',
ERROR_MIN_VALUE: 'The value must be at least ${val}.',
ERROR_MAX_VALUE: 'The value must be at most ${val}.',
ERROR_NUMBER: 'This must be a number.',
ERROR_INTEGER: 'This must be a whole number.',
ERROR_TEL: 'This is not a valid telephone number.',
ERROR_EMAIL: 'This is not a valid email address.',
ERROR_ZIP: 'This is not a valid zip code.',
ERROR_POSTAL: 'This is not a valid postal code.',
ERROR_DATE: 'This is not a valid date.',
ERROR_DATE_PAST: 'The date must be in the past.',
ERROR_DATE_FUTURE: 'The date must be in the future.',
ERROR_DATE_RANGE: 'The date is outside the allowed range.',
ERROR_DATETIME: 'This is not a valid date and time.',
ERROR_TIME: 'This is not a valid time.',
ERROR_URL: 'This is not a valid URL.',
ERROR_COLOR: 'This is not a valid CSS colour.',
ERROR_FILE_TYPE: 'This file type is not allowed.',
ERROR_FILE_MAX_FILES: 'You can upload up to ${val} file(s).',
ERROR_FILE_MAX_SIZE: 'Each file must be ${val} or smaller.',
ERROR_FILE_MIN_SIZE: 'Each file must be at least ${val}.',
ERROR_CUSTOM_VALIDATION: 'There was a problem validating this field.',
}
`

- debug - A boolean indicating whether or not to show debug messages in the console. Defaults to false.
- autoInit - A boolean indicating whether or not to automatically initialize the Validator instance on page load. Defaults to true.
- preventSubmit - A boolean indicating whether or not to prevent form submission if validation is successful. Defaults to false.
- hiddenClasses - A string containing one or more space-separated classes to toggle the hidden mode (e.g., display: none CSS property) on hidden elements. Defaults to hidden opacity-0.
- errorMainClasses - A string containing one or more space-separated classes to apply to the main error message.
- errorInputClasses - A string containing one or more space-separated classes to apply to invalid inputs.
- showMainError - A boolean indicating whether or not to show the main error message. Defaults to true.
- scrollToError - A boolean indicating whether to scroll to and focus the first invalid input when validation fails. Defaults to false.
- scrollToErrorDelay - A number (ms) to delay scroll-to-error behavior. Defaults to 0.
- validateOnBlur - A boolean indicating whether to validate fields when they lose focus, even if the value hasn't changed. Useful for showing errors on touched-but-empty required fields. Defaults to false.
- validationSuccessCallback - A function to be called when validation is successful.
- validationErrorCallback - A function to be called when validation fails.
- validators - An object mapping validator names to functions. These validators have the highest lookup priority (see Registering Custom Validators).

$3

`javascript
import Validator from '@jdlien/validator'

const myForm = document.querySelector('form')
const myValidator = new Validator(myForm, {
messages: {
ERROR_REQUIRED: 'This is required.',
ERROR_EMAIL: 'Invalid email address.',
},
debug: true,
preventSubmit: true,
hiddenClasses: 'hidden',
errorMainClasses: 'error-main',
errorInputClasses: 'error-input',
validationSuccessCallback: () => console.log('Validation successful!'),
validationErrorCallback: () => console.log('Validation failed.'),
})
`

Methods

$3

#### validateSingle(input): Promise

Validates a single input that belongs to the form and displays any error messages. Returns true if the input is valid, false otherwise.

This is useful for:

- Multi-step forms/wizards - Validate each step before allowing progression
- Dependent field validation - Validate field A when field B changes
- Custom validation triggers - Validate on demand rather than relying on events
- Dynamic form updates - Validate after programmatically updating a field's value

`javascript
const validator = new Validator(form)
const emailInput = document.getElementById('email')

// Validate a single input on demand
const isValid = await validator.validateSingle(emailInput)

if (isValid) {
// Proceed to next step
} else {
// Error messages are automatically displayed
}
`

Notes:

- Only validates inputs that belong to the validator's form
- Returns true for inputs not in the form (with console warning) or disabled inputs (use Validator.validateSingle() for standalone inputs)
- Clears previous errors before validating
- Displays error messages in the associated error element
- Works with all form control types (input, select, textarea) except radio/checkbox groups

#### clearInputErrors(input): void

Clears validation errors from a specific input element.

`javascript
validator.clearInputErrors(emailInput)
`

#### clearAllErrors(): void

Clears all validation errors from the form, including the main error message and all input errors.

`javascript
validator.clearAllErrors()
`

#### init(): void

Re-initializes the validator, refreshing the list of form inputs. Call this after dynamically adding or removing inputs.

#### destroy(): void

Removes all event listeners and restores the form's original novalidate state. Call this before removing the form from the DOM.

$3

These methods allow validation without creating a Validator instance, useful for standalone inputs outside of forms.

#### Validator.validateSingle(input, options?): Promise

Validates any input element without needing a Validator instance. Useful for standalone fields outside of forms.

`javascript
// Validate a standalone input (not in a form)
const standaloneInput = document.getElementById('standalone-email')
const isValid = await Validator.validateSingle(standaloneInput)

// With custom options
const isValid = await Validator.validateSingle(standaloneInput, {
validators: {
customCheck: (value) => value.length > 5 || 'Too short',
},
})
`

#### Validator.clearInputErrors(input, options?): void

Clears validation errors from any input element without needing a Validator instance.

`javascript
Validator.clearInputErrors(standaloneInput)
`

Events

Validator dispatches two custom events on the form during submission validation:

- validationSuccess - Fired when the form is valid.
- validationError - Fired when the form is invalid.

Both events are instances of ValidationEvent and include the original submit event as submitEvent.

Dynamic Forms and Cleanup

Validator does not watch the DOM for changes. If you add or remove inputs after initialization
(for example, injecting fields with JavaScript or swapping Blade partials), call init() again
to refresh the list of inputs and their error state.

If you remove the form from the page (such as when closing a modal or navigating in an SPA),
call destroy() first to remove event listeners and restore the form's original novalidate state.

`javascript
const validator = new Validator(form)

// After dynamically adding/removing inputs:
validator.init()

// Before removing the form from the DOM:
validator.destroy()
form.remove()
`

Utility Functions

Validator uses its own @jdlien/validator-utils for several utility functions that may be useful in your own code. You may use this package directly if you need any of these functions without using the Validator class.

If you wish to use these, you may import the functions directly from the module as an object that contains all the functions:

`javascript
// Import all the functions into a validatorUtils object
import * as validatorUtils from '@jdlien/validator-utils'
// Or just import the functions you need
import { parseDate, formatDateTime } from '@jdlien/validator-utils'
`

Here is a list of the utility functions:

Date & Time:
- parseDate: Parses a date string or Date object into a Date object.
- parseDateTime: Parses a datetime string (e.g., "tomorrow 3pm") into a Date object.
- parseTime: Parses a time string into an object with hour, minute, and second properties.
- parseRelativeDate: Parses relative date strings like "+3d", "-1w", "+2m" into a Date object.
- parseDateToString: Formats a date into a string with the specified moment.js-style format.
- parseDateTimeToString: Formats a datetime into a string with the specified format.
- parseTimeToString: Formats a time string into a formatted string.
- formatDateTime: Formats a Date object into a string with a specified format.
- momentToFPFormat: Converts a moment.js-style format string to flatpickr format.
- monthToNumber: Converts month string or number to zero-based month number (January = 0).
- yearToFull: Converts a 2-digit year to a 4-digit year.
- isDate: Determines if a value is a valid date.
- isDateTime: Determines if a value is a valid datetime.
- isTime: Determines if a value is a valid time.
- isMeridiem: Determines if a value is "am" or "pm".
- isDateInRange: Determines if a date falls within a specified range (past, future, or custom).

Numbers & Bytes:
- parseNumber: Parses a number string, stripping non-numeric characters.
- parseInteger: Parses an integer string, stripping non-digit characters.
- parseBytes: Parses human-readable byte sizes ("1.5MB", "2GiB") into bytes.
- formatBytes: Formats bytes into human-readable string (e.g., "1.5 MB").
- isNumber: Determines if a value is a valid number.
- isInteger: Determines if a value is a valid integer.

Contact & Location:
- parseNANPTel: Parses a North American phone number into standardized format.
- isNANPTel: Determines if a value is a valid North American phone number.
- isEmail: Determines if a value is a valid email address.
- parseZip: Parses a US zip code into standardized format.
- isZip: Determines if a value is a valid US zip code.
- parsePostalCA: Parses a Canadian postal code into standardized format.
- isPostalCA: Determines if a value is a valid Canadian postal code.
- parseUrl: Parses a URL, adding https:// if missing.
- isUrl: Determines if a value is a valid URL.

Color:
- parseColor: Parses any CSS color into a normalized format.
- isColor: Determines if a value is a valid CSS color.

Utilities:
- isFormControl: Determines if an element is an input, select, or textarea.
- isType: Checks if an element's type or data-type matches specified values.
- normalizeValidationResult: Normalizes validation results (boolean/string/object) into a standard format.

Breaking Changes in v2.0.0

$3

Previously, Validator used MutationObservers to automatically reinitialize when inputs changed and clean up
when forms were removed. This was inefficient and unreliable, so it has been removed.

Now, if you're dynamically changing forms/form elements in a webpage, you must run the following:
`javascript
// After dynamically adding/removing inputs:
validator.init()

// Before removing a form from the DOM:
validator.destroy()
`

$3

The separate ValidationSuccessEvent and ValidationErrorEvent classes have been replaced with a unified ValidationEvent class:

`javascript
// Before (v1.x)
form.addEventListener('validationSuccess', (e: ValidationSuccessEvent) => { ... })

// After (v2.0)
form.addEventListener('validationSuccess', (e: ValidationEvent) => { ... })
`

The ValidationEvent class has a type property that is either 'validationSuccess' or 'validationError', and a submitEvent property containing the original form submission event.

$3

- messages option typing: Now Record instead of object
- types.d.ts removed: Import types directly from the package instead:

`typescript
// Before
import type { ValidatorOptions } from '@jdlien/validator/types'

// After
import type { ValidatorOptions } from '@jdlien/validator'
`

Contributing

Install dev dependencies:

`bash
pnpm install
`

Run tests with coverage (100% required for release):

`bash
pnpm coverage
`

Build the project and demo page for testing/release:

`bash
pnpm build
``