Validation, reactive state, serialization and auto-submit for native HTML forms, with a typed, framework-free API for JavaScript and TypeScript.
Demo · Examples · Documentation · Changelog
- Installation
- Quick start
- HTML / CDN
- Capabilities
- API at a glance
- Documentation
- Changelog
- AI agent skill
- License
npm install @samline/formspnpm add @samline/formsbun add @samline/formsRequires Node 20+ when bundling; the runtime targets ES2020 browsers. Formatting needs the optional peer @samline/formatter (npm install @samline/formatter); validation, state and serialization do not. No runtime stylesheet is required; the application owns form styling.
Keep a native form with named fields. novalidate lets the controller's rules replace the browser's bubbles.
<form id="signup" novalidate>
<label for="email">Email</label>
<input id="email" name="email" type="email" autocomplete="email" aria-describedby="email-error" />
<p id="email-error" data-error-for="email" aria-live="polite"></p>
<button type="submit">Sign up</button>
</form>import { form } from '@samline/forms'
const signup = form('signup', {
autoValidate: false,
validators: {
email: {
required: { value: true, message: 'Enter your email.' },
pattern: { value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, message: 'Use a valid email.' },
},
},
})
signup.subscribe(state => {
document.querySelector('#email-error').textContent = state.errors.email?.[0] ?? ''
})
signup.onSubmit(async (_element, _data, formData) => {
await fetch('/api/signup', { method: 'POST', body: formData })
signup.reset()
})
// When the form goes away (route change, component unmount):
// signup.destroy()Invalid submits are always prevented and focus moves to the first invalid field. Valid submits reach every onSubmit() handler with a plain object, a fresh FormData and a state snapshot.
The standalone build defines window.Forms and already includes @samline/formatter. Pin the version.
<script src="https://cdn.jsdelivr.net/npm/@samline/forms@3.0.0/dist/browser/forms.global.js"></script>
<script>
const signup = window.Forms.form('signup', {
validators: { email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ } },
})
</script>window.Forms has form, newForm({ id, options }), destroyForm(id) and the available registry. See Browser global and CDN.
- Validation rules:
required,minLength,maxLength,pattern,numeric,min,max,sameAs,dependsOn, per-roweachand custom validators that read every value. - Accessible state: invalid controls get
aria-invalidandcss-error, filled onescss-filled; a failed submit focuses the first invalid control in document order. - Reactive state:
subscribe()for the whole form,observe()/watch()for one field. - Submission: promise-aware
onSubmit(),autoSubmit()with debounce,setErrors()for server responses,prefill()from the URL andreset(). - Native controls: checkbox groups, radios, multiple selects, files, repeated
name[]inputs and controls linked withform="id", including fields added later. - Formatting:
format(),formatAll()and theformatsoption format phones, cards, dates, times and amounts while a hidden field submits the raw value. - DOM-free helpers:
validateValues()andvalidateFieldValue()run the same rules on the server;parseFormData()serializes any form.
One controller owns one form's listeners, MutationObserver and auto-submit timer. Create it once the form exists and call destroy() when it goes away. addCleanup() ties your own teardown to the same lifetime. After destroy(), writes and new registrations are no-ops.
| API | Purpose |
|---|---|
form(target, options?) |
Create a controller for an id, HTMLFormElement or { current }. |
createFormController(target, options?) |
The same factory under its descriptive name. |
browser |
{ form, newForm, destroyForm, available } registry singleton. |
parseFormData(form, submitter?) |
Serialize a form into { data, formData }. |
validateValues(values, schema) |
Validate a plain values object against a ValidationSchema. |
validateFieldValue(field, value, rules, values) |
Validate one value. |
@samline/forms/browser |
The registry as a module namespace; also sets globalThis.Forms. |
@samline/forms/browser/global |
The standalone IIFE that defines window.Forms. |
| Entrypoint | When to use |
|---|---|
@samline/forms |
Controller factory, pure validation/serialization helpers and types for ESM or CommonJS. |
@samline/forms/browser |
Module registry that also installs globalThis.Forms. |
@samline/forms/browser/global |
Standalone script with window.Forms and the bundled formatter. |
| Group | Methods |
|---|---|
| Submission | onSubmit, autoSubmit, disableAutoSubmit |
| Validation | validate, revalidate, setErrors, clearErrors |
| State | subscribe, observe, watch, unwatch, getState |
| Values | setValue, setOptions, getValue, getField, getData, prefill, reset |
| Formatting | format, formatAll |
| Lifecycle | element, f, options, append, addCleanup, destroy |
validators, autoValidate (default true), autoSubmit, clearErrorsOnSubmit (default true), clearManualErrorsOnChange (default true), attributes (default { filled: 'css-filled', error: 'css-error' }) and formats. Every option is described in Configuration options; every type is exported, see the TypeScript reference.
Read the documentation for the full guides and API contracts, and explore working examples with complete and separate source files for both loading modes.
| Guide | What it covers |
|---|---|
| Get started | Installation, the first form, CDN use and cleanup. |
| Examples | Twelve live forms with their code. |
| Validation and errors | Every rule, cross-field checks and accessible messages. |
| State and submission | Subscribers, async submits, auto-submit, prefill and reset. |
| Formatting fields | The optional formatter and the hidden raw mirror. |
| Framework integrations | React, Vue, Svelte, Astro, Shopify and WordPress. |
| API reference | Every method, grouped by task, with one page per method. |
Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.
2.8.0 removes no API. Review these behavior fixes before upgrading: prefill() writes repeated query keys as arrays and auto-submits once; native reset buttons now clear errors and attributes; reset() calls watchers; failed submits focus the first invalid control in document order and automatic submits never move focus; methods called after destroy() no longer change the form; rejected async submit handlers are logged. The Markdown docs/ folder is no longer published to npm; the documentation lives on the website. The optional @samline/formatter peer now requires ^2.1.0, which the standalone script bundles. Read the 2.8.0 notes.
The Forms skill describes 2.8 integration: loading modes, validation rules and accessible messages, state and submission, formatting and host ownership. Pass it to an agent or install it using a skills-compatible tool. Verify the installed package version before applying its guidance.
The maintained repository source and website download are the same file.
Download SKILL.md into a forms/ folder in your agent's supported skill directory. For agents that discover project skills from .agents/skills/:
mkdir -p .agents/skills/forms
curl --fail --location https://samline.github.io/forms/skills/forms/SKILL.md \
--output .agents/skills/forms/SKILL.mdWhen working from this repository, copy skills/forms/SKILL.md instead. Keep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.
MIT — LICENSE.md.