# checkValidity vs reportValidity: Core Behavioral Differences

The core divergence between checkValidity() and reportValidity() lies in their side-effect profiles: checkValidity() performs a silent boolean evaluation, while reportValidity() evaluates state AND triggers native browser UI, focus management, and event dispatch.

For teams architecting scalable validation layers, understanding these primitives is foundational to Mastering HTML5 Native Form Validation. Use the following decision matrix to select the correct API:

# How checkValidity() Works: Silent State Evaluation

checkValidity() synchronously evaluates all HTML5 constraint attributes (required, pattern, min, max, type, etc.) and returns a boolean. It intentionally bypasses the browser’s rendering pipeline, making it ideal for background logic, state management, and custom UI synchronization without triggering visual thrashing.

const input = document.querySelector<HTMLInputElement>('#email');

if (input) {
 const isValid = input.checkValidity();
 
 if (!isValid) {
 // Safe to log, track, or apply custom classes without UI side effects
 console.warn('Validation failed:', input.validationMessage);
 input.classList.add('custom-error');
 // Manual A11y sync required:
 input.setAttribute('aria-invalid', 'true');
 input.setAttribute('aria-describedby', `${input.id}-error-msg`);
 }
}

Key Behaviors & Edge Cases:

• Does not automatically dispatch the invalid event.
• Ignores novalidate on parent <form> elements.
• Returns true immediately for disabled or readonly fields.
• Requires manual aria-invalid and aria-describedby updates for screen reader compliance.

# How reportValidity() Works: UI Feedback & Accessibility Triggers

reportValidity() returns the same boolean as checkValidity() but additionally triggers the browser’s native validation UI. This includes rendering native tooltips, scrolling the viewport, focusing the first invalid field, and dispatching the invalid event. It fully respects the constraint validation pipeline and integrates seamlessly with broader form architecture, as detailed in the Constraint Validation API Deep Dive.

const form = document.querySelector<HTMLFormElement>('#signup-form');

if (form) {
 const isValid = form.reportValidity();
 
 if (!isValid) {
 // Native browser handles:
 // 1. Tooltip rendering
 // 2. Focus & scroll to invalid field
 // 3. 'invalid' event dispatch
 // 4. ARIA live region announcements (compliant browsers)
 return;
 }
 
 // Proceed with async submission
 submitFormData(form);
}

Key Behaviors & Edge Cases:

• Respects form.novalidate (returns true without UI if attribute is present).
• Safari may delay tooltip rendering or suppress it in certain contexts.
• Focus stealing can disrupt keyboard navigation if invoked on rapid input/keydown events.
• Automatically announces errors via ARIA live regions in modern browsers.

# Implementation Matrix: Form Submission vs Real-Time UX

Mixing these methods incorrectly causes UX degradation, performance bottlenecks, or accessibility violations. Follow these production patterns:

// ✅ Progressive validation on blur/input
const handleFieldBlur = (e: Event) => {
 const target = e.target as HTMLInputElement;
 if (target.checkValidity()) {
 target.classList.remove('custom-error');
 target.removeAttribute('aria-invalid');
 } else {
 target.classList.add('custom-error');
 target.setAttribute('aria-invalid', 'true');
 // Optionally show custom message here
 }
};

// ✅ Form submission gate
form.addEventListener('submit', (e: SubmitEvent) => {
 e.preventDefault();
 
 // Use checkValidity() for fast synchronous gate
 if (!form.checkValidity()) {
 // Delegate to native UI only on explicit user action (submit)
 form.reportValidity();
 return;
 }

 // Proceed with async submission
 handleAsyncSubmit(form);
});

Critical Rules:

• Use checkValidity() for debounced real-time validation.
• Use reportValidity() on submit or explicit user action.
• Never chain reportValidity() on every keystroke. It forces synchronous DOM layout thrashing, steals focus, and degrades main-thread performance.

# Edge Cases & Browser Quirks

Native validation behaves inconsistently across rendering engines and component boundaries. Apply these fallback strategies:

• Shadow DOM / Web Components: reportValidity() may not cross shadow boundaries. Manually call reportValidity() on the host element or use form.reportValidity() with form.elements scoped to light DOM.
• Safari Tooltip Positioning: Safari occasionally misplaces native tooltips on transformed or fixed-position inputs. Provide a CSS fallback or custom overlay for critical paths.
• pattern Unicode Handling: Some browsers fail to validate complex Unicode regex patterns. Test with u flag equivalents or validate server-side.
• novalidate Override: If form.novalidate is toggled dynamically, reportValidity() will silently return true. Always verify !form.novalidate before relying on native UI.

Troubleshooting Checklist:

1. Verify form.elements vs querySelectorAll scope for nested components.
2. Check for novalidate attribute overriding reportValidity().
3. Test focus management in Safari vs Chromium.
4. Clear setCustomValidity('') before re-running validation cycles.

# Debugging Protocol: Why Validity States Diverge

When checkValidity() returns true but reportValidity() shows errors (or vice versa), the issue typically stems from stale custom validity messages, willValidate state mismatches, or event propagation interference.

const debugValidity = (el: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement) => {
 console.group('Validity Debug');
 console.log('willValidate:', el.willValidate);
 console.log('validity:', { ...el.validity });
 console.log('checkValidity():', el.checkValidity());
 console.log('validationMessage:', el.validationMessage);
 console.log('customValidity:', el.validationMessage === el.validationMessage ? 'Set' : 'None');
 console.groupEnd();
};

Actionable Takeaway: Stale custom validity messages are the #1 cause of state divergence. The browser caches setCustomValidity() strings until explicitly cleared. Always reset with el.setCustomValidity('') before re-evaluating constraints or switching validation strategies.