form-vanilla
Framework-free form validation using HTML5 Constraint Validation API enhanced with Zod for complex rules. Use when building forms without React/Vue or for progressive enhancement.
When & Why to Use This Skill
This Claude skill provides a robust, framework-free form validation solution by combining the native HTML5 Constraint Validation API with Zod's powerful schema modeling. It enables developers to build lightweight, accessible, and highly performant web forms with complex validation rules, making it an ideal choice for projects where React or Vue might be overkill or for implementing progressive enhancement strategies.
Use Cases
- Lightweight Web Development: Building high-performance landing pages or static sites that require complex form logic without the bundle size overhead of a JavaScript framework.
- Progressive Enhancement: Ensuring forms remain functional with native browser validation while providing an enhanced, real-time validation experience when JavaScript is enabled.
- Complex Schema Validation: Leveraging Zod to handle intricate validation rules, such as cross-field dependencies or custom logic, that native HTML5 attributes cannot express alone.
- Accessible UI/UX: Implementing ARIA-compliant error messaging and real-time feedback loops (blur/input/submit) to improve form usability and accessibility for all users.
- Modernizing Legacy Projects: Adding type-safe, schema-based validation to existing vanilla JavaScript or jQuery projects without a full architectural rewrite.
| name | form-vanilla |
|---|---|
| description | Framework-free form validation using HTML5 Constraint Validation API enhanced with Zod for complex rules. Use when building forms without React/Vue or for progressive enhancement. |
Form Vanilla
Framework-free form patterns using native browser APIs enhanced with Zod.
Quick Start
<form id="login-form" novalidate>
<div class="form-field">
<label for="email">Email</label>
<input
id="email"
name="email"
type="email"
autocomplete="email"
required
/>
<span class="error" aria-live="polite"></span>
</div>
<div class="form-field">
<label for="password">Password</label>
<input
id="password"
name="password"
type="password"
autocomplete="current-password"
required
minlength="8"
/>
<span class="error" aria-live="polite"></span>
</div>
<button type="submit">Sign in</button>
</form>
<script type="module">
import { createFormValidator } from './vanilla-validator.js';
import { loginSchema } from './schemas.js';
const form = document.getElementById('login-form');
const validator = createFormValidator(form, loginSchema);
form.addEventListener('submit', async (e) => {
e.preventDefault();
const result = await validator.validate();
if (result.valid) {
console.log('Submit:', result.data);
}
});
</script>
HTML5 Constraint Validation API
Built-in Attributes
<!-- Required field -->
<input required />
<!-- Length constraints -->
<input minlength="3" maxlength="50" />
<!-- Number constraints -->
<input type="number" min="0" max="100" step="1" />
<!-- Pattern (regex) -->
<input pattern="[A-Za-z]{3}" title="Three letter code" />
<!-- Email validation -->
<input type="email" />
<!-- URL validation -->
<input type="url" />
Validity State Properties
const input = document.querySelector('input');
// Check individual constraints
input.validity.valueMissing; // required but empty
input.validity.typeMismatch; // email/url format wrong
input.validity.patternMismatch; // regex failed
input.validity.tooShort; // < minlength
input.validity.tooLong; // > maxlength
input.validity.rangeUnderflow; // < min
input.validity.rangeOverflow; // > max
input.validity.stepMismatch; // not divisible by step
input.validity.badInput; // browser can't parse
input.validity.customError; // setCustomValidity called
// Check overall validity
input.validity.valid; // all constraints pass
input.checkValidity(); // returns boolean
input.reportValidity(); // shows browser UI
Custom Error Messages
const input = document.querySelector('#email');
// Set custom validation message
input.addEventListener('invalid', (e) => {
if (input.validity.valueMissing) {
input.setCustomValidity('Please enter your email address');
} else if (input.validity.typeMismatch) {
input.setCustomValidity('Please enter a valid email (e.g., name@example.com)');
}
});
// Clear custom message on input
input.addEventListener('input', () => {
input.setCustomValidity('');
});
Zod Integration
Vanilla Validator Class
// vanilla-validator.ts
import { z } from 'zod';
export interface ValidationResult<T> {
valid: boolean;
data?: T;
errors: Record<string, string>;
}
export interface ValidatorOptions {
/** When to validate */
validateOn: 'blur' | 'input' | 'submit';
/** When to re-validate after error */
revalidateOn: 'input' | 'blur';
/** Debounce delay for input validation (ms) */
debounceMs?: number;
}
const defaultOptions: ValidatorOptions = {
validateOn: 'blur',
revalidateOn: 'input',
debounceMs: 300
};
export function createFormValidator<T extends z.ZodType>(
form: HTMLFormElement,
schema: T,
options: Partial<ValidatorOptions> = {}
): FormValidator<z.infer<T>> {
const opts = { ...defaultOptions, ...options };
const fieldErrors = new Map<string, string>();
const touchedFields = new Set<string>();
let debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
// Get all form fields
const fields = Array.from(form.elements).filter(
(el): el is HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement =>
el instanceof HTMLInputElement ||
el instanceof HTMLSelectElement ||
el instanceof HTMLTextAreaElement
);
// Attach event listeners
fields.forEach(field => {
if (!field.name) return;
// Blur handler (punish late)
field.addEventListener('blur', () => {
touchedFields.add(field.name);
if (opts.validateOn === 'blur') {
validateField(field.name);
}
});
// Input handler (real-time correction)
field.addEventListener('input', () => {
// Clear existing timer
const timer = debounceTimers.get(field.name);
if (timer) clearTimeout(timer);
// Only validate if already has error (correction mode)
if (fieldErrors.has(field.name) && opts.revalidateOn === 'input') {
debounceTimers.set(
field.name,
setTimeout(() => validateField(field.name), opts.debounceMs)
);
}
});
});
function getFormData(): Record<string, unknown> {
const data: Record<string, unknown> = {};
const formData = new FormData(form);
formData.forEach((value, key) => {
// Handle checkboxes
const field = form.elements.namedItem(key);
if (field instanceof HTMLInputElement && field.type === 'checkbox') {
data[key] = field.checked;
} else if (field instanceof HTMLInputElement && field.type === 'number') {
data[key] = value === '' ? undefined : Number(value);
} else {
data[key] = value;
}
});
return data;
}
function validateField(name: string): string | undefined {
const data = getFormData();
const result = schema.safeParse(data);
if (result.success) {
clearFieldError(name);
return undefined;
}
const fieldError = result.error.errors.find(e => e.path[0] === name);
if (fieldError) {
setFieldError(name, fieldError.message);
return fieldError.message;
} else {
clearFieldError(name);
return undefined;
}
}
function setFieldError(name: string, message: string): void {
fieldErrors.set(name, message);
const field = form.elements.namedItem(name) as HTMLInputElement | null;
if (!field) return;
// Set ARIA attributes
field.setAttribute('aria-invalid', 'true');
// Find error element
const fieldWrapper = field.closest('.form-field');
const errorEl = fieldWrapper?.querySelector('.error');
if (errorEl) {
errorEl.textContent = message;
field.setAttribute('aria-describedby', errorEl.id || '');
}
// Add error class
fieldWrapper?.classList.add('has-error');
fieldWrapper?.classList.remove('is-valid');
// Set custom validity for native UI
field.setCustomValidity(message);
}
function clearFieldError(name: string): void {
fieldErrors.delete(name);
const field = form.elements.namedItem(name) as HTMLInputElement | null;
if (!field) return;
// Clear ARIA
field.setAttribute('aria-invalid', 'false');
field.removeAttribute('aria-describedby');
// Clear error element
const fieldWrapper = field.closest('.form-field');
const errorEl = fieldWrapper?.querySelector('.error');
if (errorEl) {
errorEl.textContent = '';
}
// Update classes
fieldWrapper?.classList.remove('has-error');
if (touchedFields.has(name)) {
fieldWrapper?.classList.add('is-valid');
}
// Clear custom validity
field.setCustomValidity('');
}
function clearAllErrors(): void {
fieldErrors.forEach((_, name) => clearFieldError(name));
}
async function validate(): Promise<ValidationResult<z.infer<T>>> {
const data = getFormData();
const result = schema.safeParse(data);
if (result.success) {
clearAllErrors();
return { valid: true, data: result.data, errors: {} };
}
// Set errors for all fields
const errors: Record<string, string> = {};
result.error.errors.forEach(err => {
const name = String(err.path[0]);
errors[name] = err.message;
setFieldError(name, err.message);
});
// Focus first error
const firstErrorName = Object.keys(errors)[0];
if (firstErrorName) {
const field = form.elements.namedItem(firstErrorName) as HTMLElement;
field?.focus();
}
return { valid: false, errors };
}
function reset(): void {
form.reset();
clearAllErrors();
touchedFields.clear();
debounceTimers.forEach(timer => clearTimeout(timer));
debounceTimers.clear();
}
return {
validate,
validateField,
setFieldError,
clearFieldError,
clearAllErrors,
reset,
getFormData
};
}
export interface FormValidator<T> {
validate(): Promise<ValidationResult<T>>;
validateField(name: string): string | undefined;
setFieldError(name: string, message: string): void;
clearFieldError(name: string): void;
clearAllErrors(): void;
reset(): void;
getFormData(): Record<string, unknown>;
}
Usage Example
<!DOCTYPE html>
<html>
<head>
<style>
.form-field {
margin-bottom: 1rem;
}
.form-field label {
display: block;
margin-bottom: 0.25rem;
}
.form-field input {
width: 100%;
padding: 0.5rem;
border: 1px solid #ccc;
border-radius: 4px;
}
.form-field.has-error input {
border-color: #dc2626;
}
.form-field.is-valid input {
border-color: #059669;
}
.form-field .error {
color: #dc2626;
font-size: 0.875rem;
margin-top: 0.25rem;
}
</style>
</head>
<body>
<form id="contact-form" novalidate>
<div class="form-field">
<label for="name">Name</label>
<input id="name" name="name" type="text" autocomplete="name" />
<span class="error" id="name-error" aria-live="polite"></span>
</div>
<div class="form-field">
<label for="email">Email</label>
<input id="email" name="email" type="email" autocomplete="email" />
<span class="error" id="email-error" aria-live="polite"></span>
</div>
<div class="form-field">
<label for="message">Message</label>
<textarea id="message" name="message" rows="4"></textarea>
<span class="error" id="message-error" aria-live="polite"></span>
</div>
<button type="submit">Send</button>
</form>
<script type="module">
import { z } from 'https://cdn.jsdelivr.net/npm/zod@3/+esm';
import { createFormValidator } from './vanilla-validator.js';
const schema = z.object({
name: z.string().min(1, 'Please enter your name'),
email: z.string().email('Please enter a valid email'),
message: z.string().min(10, 'Message must be at least 10 characters')
});
const form = document.getElementById('contact-form');
const validator = createFormValidator(form, schema);
form.addEventListener('submit', async (e) => {
e.preventDefault();
const result = await validator.validate();
if (result.valid) {
console.log('Submitting:', result.data);
// Send to server...
alert('Message sent!');
validator.reset();
}
});
</script>
</body>
</html>
Progressive Enhancement
Base HTML (Works Without JS)
<form action="/submit" method="POST">
<div class="form-field">
<label for="email">Email *</label>
<input
id="email"
name="email"
type="email"
required
autocomplete="email"
/>
</div>
<div class="form-field">
<label for="password">Password *</label>
<input
id="password"
name="password"
type="password"
required
minlength="8"
autocomplete="current-password"
/>
</div>
<button type="submit">Sign in</button>
</form>
Enhanced With JS
// Only runs if JS is available
const form = document.querySelector('form');
if (form) {
// Disable native validation UI
form.setAttribute('novalidate', '');
// Add ARIA live regions for errors
form.querySelectorAll('.form-field').forEach(field => {
const input = field.querySelector('input');
if (input && input.name) {
const errorEl = document.createElement('span');
errorEl.className = 'error';
errorEl.id = `${input.name}-error`;
errorEl.setAttribute('aria-live', 'polite');
field.appendChild(errorEl);
}
});
// Attach validator
const validator = createFormValidator(form, schema);
form.addEventListener('submit', async (e) => {
e.preventDefault();
const result = await validator.validate();
if (result.valid) {
form.submit(); // Native submit
}
});
}
Common Patterns
Password Visibility Toggle
<div class="form-field password-field">
<label for="password">Password</label>
<div class="input-wrapper">
<input
id="password"
name="password"
type="password"
autocomplete="current-password"
/>
<button
type="button"
class="toggle-password"
aria-label="Show password"
>
👁
</button>
</div>
</div>
<script>
document.querySelectorAll('.toggle-password').forEach(btn => {
btn.addEventListener('click', () => {
const input = btn.previousElementSibling;
const isPassword = input.type === 'password';
input.type = isPassword ? 'text' : 'password';
btn.setAttribute('aria-label', isPassword ? 'Hide password' : 'Show password');
btn.textContent = isPassword ? '🙈' : '👁';
});
});
</script>
Character Counter
<div class="form-field">
<label for="bio">Bio</label>
<textarea id="bio" name="bio" maxlength="500"></textarea>
<span class="char-count"><span id="bio-count">0</span>/500</span>
</div>
<script>
const textarea = document.getElementById('bio');
const counter = document.getElementById('bio-count');
textarea.addEventListener('input', () => {
counter.textContent = textarea.value.length;
});
</script>
Form Submission with Fetch
const form = document.getElementById('my-form');
const submitBtn = form.querySelector('button[type="submit"]');
form.addEventListener('submit', async (e) => {
e.preventDefault();
const result = await validator.validate();
if (!result.valid) return;
// Disable button
submitBtn.disabled = true;
submitBtn.textContent = 'Sending...';
try {
const response = await fetch(form.action, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': document.querySelector('[name="_csrf"]').value
},
body: JSON.stringify(result.data)
});
if (!response.ok) {
const error = await response.json();
// Handle server errors
if (error.field) {
validator.setFieldError(error.field, error.message);
} else {
alert(error.message);
}
return;
}
// Success
alert('Form submitted!');
validator.reset();
} catch (err) {
alert('Network error. Please try again.');
} finally {
submitBtn.disabled = false;
submitBtn.textContent = 'Submit';
}
});
File Structure
form-vanilla/
├── SKILL.md
├── references/
│ └── constraint-validation.md # HTML5 Constraint API reference
└── scripts/
├── vanilla-validator.ts # Main validator class
├── vanilla-validator.js # Compiled JS
├── progressive-enhance.js # Progressive enhancement utils
└── examples/
├── login-form.html
├── contact-form.html
└── checkout-form.html
Reference
references/constraint-validation.md— HTML5 Constraint Validation API reference