ValidityState API: JavaScript Form Validation Made Simple

What is ValidityState?

The ValidityState interface represents the validity states that an HTML form element can be in with respect to constraint validation. Every form-associated element exposes a validity property that returns a ValidityState object containing read-only boolean properties indicating which specific validation constraints are being violated.

This granular approach means you can determine exactly why validation failed and respond accordingly--whether showing a specific error message, highlighting the problematic field, or preventing form submission entirely. For teams building professional web applications, leveraging native browser APIs like ValidityState delivers superior performance without external dependencies.

When you access an element's validity property, you receive an object with multiple properties that reflect different aspects of the element's validation state. The most important property is the valid property, which is true only when all validation constraints are satisfied. This interface is supported across all modern browsers and provides a reliable foundation for client-side form validation. Unlike custom validation solutions that require significant JavaScript code to check each constraint manually, ValidityState leverages the browser's native constraint validation machinery.

For performance-conscious applications, particularly those built on the Next.js framework, using native browser validation reduces JavaScript execution time and improves Core Web Vitals scores. The lightweight nature of native validation also supports accessibility requirements by ensuring fast, responsive interactions for all users.

MDN Web Docs on Constraint Validation

Accessing ValidityState in JavaScript

Accessing an element's validity is straightforward--simply reference the validity property of any form-associated element. The returned object provides immediate access to all boolean properties without requiring additional processing. This direct access pattern makes ValidityState extremely efficient for validation logic.

Unlike approaches that require parsing error messages or implementing custom validation functions, the ValidityState API provides a direct, boolean answer to each validation question. For React and Next.js applications, this pattern integrates naturally with component state management--you can check validity in event handlers and update state accordingly without additional dependencies. When implementing comprehensive form solutions, this native approach reduces bundle size and maintenance overhead.

Creating Custom Validation Messages

Custom validation messages help users understand exactly what went wrong and how to fix it. Browser defaults are often generic and unhelpful--custom messages provide context-specific guidance. The fundamental pattern involves checking the validity state and returning an appropriate message string based on which specific constraint failed.

For forms with multiple fields, organizing validation logic by field name provides better maintainability and allows field-specific messages. This pattern groups validation rules by field identifier, enabling each field to have unique message requirements while sharing the underlying ValidityState checking mechanism. This organizational approach becomes especially valuable when fields have different validation requirements, such as contact forms that include email validation alongside phone number formatting.

Cloud Four's guide on ValidityState provides additional patterns for field-specific validation logic.

Accessibility Considerations

Accessible validation ensures all users, including those using screen readers, can understand and resolve validation errors. The ValidityState API enables creating messages that explain problems clearly, but additional HTML attributes are necessary to ensure these messages are properly associated with their fields and announced to assistive technologies. Implementing accessible forms is essential for inclusive web experiences.

Key Techniques

aria-describedby creates a programmatic association between form fields and their error messages. When this association exists, screen readers will announce the error message when focus moves to the field, ensuring visually hidden or off-screen messages remain accessible.

aria-invalid signals validation state to assistive technologies, allowing users to quickly identify which fields require attention:

if (inputEl.validity.valid) {
 inputEl.setAttribute('aria-invalid', 'false');
} else {
 inputEl.setAttribute('aria-invalid', 'true');
}

aria-live="polite" ensures error messages are announced without interrupting other announcements. For form submission errors that appear all at once, consider using "assertive" instead to ensure critical information is communicated immediately.

Best Practices for Modern Web Applications

Progressive Enhancement

Forms should function meaningfully even without JavaScript. Native HTML attributes like required, pattern, and type create validation that works without scripts. JavaScript enhancement layers custom messages and real-time feedback on this baseline. This progressive enhancement approach ensures that all users receive functional validation while those with JavaScript enabled enjoy an improved experience.

Writing Helpful Messages

Effective validation messages are:

• Specific: Identify exactly which constraint failed and explain it in terms users understand
• Constructive: Helpful tone, not punitive--users aren't trying to enter invalid data
• Clear: Provide examples or explanations when the format requirements aren't obvious

Server-Side Validation

Client-side validation improves UX but never replaces server-side validation. Users can disable JavaScript or craft requests manually. Always validate on the server using similar logic to client-side checks. Effective web applications implement defense in depth, with server-side validation that mirrors client-side rules. For robust full-stack implementations, server-side validation ensures data integrity regardless of client capabilities.

MDN's constraint validation documentation emphasizes the importance of server-side validation as a necessary complement to client-side checks.

Sources

1. MDN Web Docs - Constraint Validation - Official documentation on HTML5 constraint validation, covering basic constraints, validation attributes, and the Constraint Validation API methods.

2. Cloud Four - Custom Validation Messages - Practical guide on the ValidityState API with code examples for custom validation messages, accessibility considerations, and progressive enhancement patterns.