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-independent solution for web form validation by bridging native browser capabilities with modern schema validation. It leverages the HTML5 Constraint Validation API for performance and accessibility, while integrating Zod to handle complex business logic and data transformation. It is ideal for developers seeking a lightweight, high-performance alternative to heavy framework-based form libraries, supporting progressive enhancement and ARIA-compliant error handling.
Use Cases
- Developing lightweight landing pages or static websites where importing React, Vue, or Angular would be unnecessary overhead.
- Implementing progressive enhancement to ensure web forms remain functional and valid even in environments where JavaScript is disabled or fails to load.
- Modernizing legacy codebases by introducing Zod-based schema validation without the need for a full frontend framework migration.
- Creating highly accessible forms that automatically manage ARIA attributes and focus states for screen readers during validation errors.
- Building high-performance web components or micro-frontends that require isolated and dependency-minimal form logic.
| 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