Placeholders and typing help derived from the HTML pattern attribute.
You write one regular expression in pattern="…". The browser already uses it
to validate the field. formaton reads the same pattern and works out what the user
can type next. It can then:
- insert characters the pattern forces:
(212becomes(212)for\(\d{3}\) \d{3}-\d{4} - repair pasted or prefilled values:
2125551234becomes(212) 555-1234 - fix letter case when only the other case fits:
abcdbecomesABCDfor[A-Z]{4} - erase separators together with the character before them on backspace
- generate placeholders:
(___) ___-____, or a sample value such as(000) 000-0000, including ghost text after a partial value:(212) ___-____ - compute min/max length, for
maxlength
<input pattern="\(\d{3}\) \d{3}-\d{4}">
<input type="email">
<input type="number" min="1" max="12">
<script type="module">
import { attachAll } from 'formaton';
attachAll(document, {
autoAdvance: true, // "press Tab" once a field is filled
onComplete: (value, field) => field.element.classList.add('valid'),
onFilled: (value, field) => console.log('done', value, field.rawValue),
onReject: (text, field) => console.log('does not fit:', text),
});
</script>attach(element, options) does the same for one <input> or <textarea>
and returns a binding (attachAll(root, options) returns all the bindings that
do something). The pattern comes from options.pattern, then the pattern
attribute, then the type:
| Field | What formaton does |
|---|---|
any text-like input with a pattern (text, tel, search, url, password), <textarea> with options.pattern |
full typing help: separators, case, paste, backspace, editing in the middle |
type="email" |
the email grammar from the HTML standard, as a pattern; never "filled", since an address can always grow |
type="number" with integer min/max (and step 1) |
characters the range never uses (-, e, ., letters) are stopped before they get in; digits that cannot lead to a number in range are reverted; "filled" once no further digit fits (with max="12", after 2 or 12, not after 1) |
date, month, week, time, datetime-local |
the browser's own widget does the typing; formaton only reports "filled" (not while a year is half typed). Chrome turns segments left at 00 into 01 on blur (01/01/0001 is a valid date), so give the field a min |
| anything else | nothing (binding.kind === 'none') |
Options:
onComplete(value, binding): the value has become valid.123for a CVV of\d{3,4},12345for\d{5}(-\d{4})?. More may still follow, so focus stays.onFilled(value, binding): the value is valid and nothing more can be typed. A full phone number counts, and so does a 4-digit CVV; five digits of a ZIP code do not, because-1234may follow. This is whenautoAdvancemoves on.onReject(text, binding): typed or pasted text that does not fit. This includes typing past the end. The text is not inserted.autoAdvance: move focus to the next field in tab order once filled. If formaton itself typed the last characters (theMof9:30PMafter you typedp), the same keys typed right after (within 1.5 s) are dropped instead of landing in the next field. This only happens if the caret is at the end, so finishing an edit in the middle does not jump away. Scripts cannot press Tab, sofocusNext(element)does what Tab would: it followstabindex, and skips hidden, disabled and inert elements and the extra buttons of a radio group. It is exported too.editMode: what typing in the middle of a value does to the characters after the caret.overwritereplaces them one by one,shiftmoves them along (what no longer fits is lost),truncateclears them. The default,auto, shifts while the field still has room and overwrites once it is filled. Deleting always pulls the rest back, except withtruncate.- Separators formaton inserts by itself stay on Backspace while the character
before them stays:
1QWS1-1becomes1QWS1-, the next Backspace gives1QWS. Optional ones (the-of a ZIP+4 code) are the user's to type or delete like any other character. onFilled(andautoAdvance) fire again when the user re-types the last character of a filled value, so correcting a field moves on just like filling it did.animate(default true): characters formaton adds at the end are typed out one by one, 15 ms each and at most 200 ms in all, so the user sees them arrive. A number sets the milliseconds per character;falseturns it off. It is off when the user prefers reduced motion. Any key, click or paste finishes it at once, so typing on never waits.prefix(default true): on focus, fill in what every value starts with (+1 (), keep it while focused, and clear it on blur if nothing else was typed.placeholder('auto'|'mask'|'example'|false): with'auto', a mask such as(___) ___-____is set when the field has no placeholder and every value has that shape: fixed length, with fixed characters to show. For lengths that vary (card numbers of several brands, IP addresses) a mask would mislead, so none is set.maskCharchanges the_.maxLength(default false): setmaxlengthfrom the pattern. It is off because formaton enforces the length itself, and atmaxlengthbrowsers swallow keystrokes (soonRejectcannot fire) and truncate pastes before formaton can reformat them.
Every option can also be set per field in the HTML, with data-formaton-*
attributes that win over the options passed in: data-formaton-prefix="false",
data-formaton-animate="30", data-formaton-auto-advance,
data-formaton-edit-mode="shift", data-formaton-placeholder="mask",
data-formaton-mask-char="#", data-formaton-max-length, data-formaton-pattern. Or
pass attachAll a function that returns each element's options:
attachAll(form, (el) => ({ autoAdvance: true, prefix: !el.matches('.pasted') }));For example, crypto addresses are nearly always pasted, and a field that
already shows bc1 on focus can confuse people:
<input pattern="bc1[ac-hj-np-z02-9]{11,71}" data-formaton-prefix="false">The field stays empty on focus; typing q still gives bc1q, and pasting a
full address works either way.
A binding has element, formaton (the compiled pattern), kind, complete,
filled,
a read/write rawValue (2125551234), and detach().
Notes:
- formaton sets
element.valueitself. That does not fireinputevents, and in Chrome it clears the field's undo history. Frameworks that keep their own copy of the value (React's controlled inputs) need to read it back inonFilledor onchange. - IME composition is left alone until it ends, then handled as one insertion.
- A rejected character changes nothing: the value, the caret and any selection stay as they were. Only characters that fit replace anything.
- Characters the pattern requires are added as soon as the value needs them,
wherever the caret is:
(212gives(212),2012gives2012-,JagivesJanuarywhen a year must follow. - Separators formaton has just inserted can be typed once more, out of habit:
-after2012(which became2012-),)or)after(212,+1 (after focusing a field that starts with it. A second-, or a1after+1 ((area codes cannot start with 1), is rejected like any misfit. Moving the caret ends that chance. Separators ahead of the caret are stepped over (12|:54plus:). type="email"fields have no caret API, and setting their value moves the caret to the end. formaton turns the field into a text field for an instant to put the caret back.
import { compile } from 'formaton';
const phone = compile(String.raw`\(\d{3}\) \d{3}-\d{4}`);
phone.prefix(); // "("
phone.forced('(212'); // ") "
phone.fix('2125551234').value; // "(212) 555-1234"
phone.trimForced('(212) '); // "(212"
phone.example({ mask: '_' }); // "(___) ___-____"
phone.mask('212'); // "(212) ___-____"
phone.mask('(212) 5'); // "(212) 5__-____"
phone.test('(212) 555-1234'); // true
phone.maxLength(); // 14
phone.unformat('(212) 555-1234'); // "2125551234"
phone.format('2125551234').value; // "(212) 555-1234"
phone.minValueLength(); // 10
phone.maxValueLength(); // 10compile(pattern, { mode }) returns a Formaton. mode is 'v', 'u' or
'auto' (default). Browsers compile pattern with the v flag, and auto
does the same wherever the JS engine supports it. An invalid pattern throws
FormatonSyntaxError. A valid pattern that an automaton cannot model throws
FormatonUnsupportedError; leave such fields unassisted.
All matching is full-string, as in the browser: ^(?:pattern)$.
| Method | Returns |
|---|---|
test(value) |
true if value matches |
isPrefix(value) |
true if value can still be completed into a match |
allowedNext(value) |
CharSet of possible next characters, or null at a dead end |
forced(value) |
the characters that must come next (stops once value is a complete match) |
prefix() |
forced(''): what every match starts with |
fix(value, { caseFix, insertForced, drop }) |
{ value, ok, complete, rejected }; value is always a viable prefix |
trimForced(value) |
value without trailing characters the pattern would insert by itself |
example({ value, length, mask, random }) |
a matching string, or null if none exists |
mask(value, { char, length }) |
example() with mask: '_': (212) ___-____ |
autoChars(value) |
per character: would formaton have inserted it by itself? |
unformat(value, from?) |
the raw value: only the characters the user chose, e.g. 2125551234 |
format(raw) |
{ value, ok, complete }: the inverse of unformat(), strict about its input |
minLength(), maxLength() |
lengths in UTF-16 code units (as maxlength counts them); Infinity if unbounded |
minValueLength(), maxValueLength() |
the same for the raw value: 10 and 10 for a US phone number |
integerRangePattern(lo, hi) |
(function) a pattern for the integers lo..hi, as used for type="number" |
fix() options all default to on, except drop:
caseFixflips a letter's case if only the other case is allowed.insertForcedadds separators the user skipped.dropskips characters that cannot be placed. Without it,fix()stops at the first such character and reportsok: false.
A character is forced where the pattern allows exactly one character at that
position. forced() stops once the value is a complete match, so a ZIP code
does not grow a - after five digits. unformat(), format() and fix()
look past that point: 12345-6789 unformats to 123456789, and both
format('123456789') and fix('123456789') give back 12345-6789.
fix() needs no hint about whether its input is raw or formatted. It weighs
every reading (each character typed as is, with its case flipped, or after
inserted single-choice characters) and keeps the one that fits the most input,
preferring complete matches and then the fewest changes. For \+1 \d{10},
12125551234 becomes +1 2125551234 (country code typed), while 1212555123
becomes +1 1212555123. format() is the strict, exact inverse of
unformat(), for raw values you stored yourself. If a pattern ends in an optional forced character, like
the - of \d{3}-?, the raw value cannot record whether it was there, and
format() leaves it out.
example() options:
valueis completed instead of starting empty. It goes throughfix()like anything typed or pasted, so raw (212), formatted ((212) and half-formatted input all work, and whatever does not fit is rejected.length: 'max'produces the longest match. It falls back to the shortest when the pattern is unbounded.maskreplaces every character the user would have to choose.randomsupplies a random-number function for varied sample values.
Everything an automaton can model:
- literals and all escapes (
\d \w \s,\x41,A,\u{1F600},\cJ, …) ., classes and negated classesv-mode nested classes,&&,--and\q{…}\p{…}/\P{…}: Unicode properties, resolved through the JS engine, so no tables are bundled- groups, named groups, alternation
- every quantifier (counts up to 10,000)
^and$
Not supported: backreferences, lookahead and lookbehind, \b / \B, modifier
groups (?i:…), and properties of strings (\p{RGI_Emoji}).
With Docker (or podman), no Node.js needed on the host:
make serve # demo at http://localhost:8080/demo/
make test # engine tests
make test-browser # DOM binding, typed into real Chromium
make build # compile to dist/
make pack # build formaton-<version>.tgz, as it would go to npm
make help # everything elseThe image keeps its node_modules outside the source tree, which is mounted
into the container, so your checkout stays clean apart from dist/ (and the
.tgz from make pack). make update-lock-file writes package-lock.json.
With Node.js 22 or later installed, the same tasks are npm scripts:
npm test # builds with tsc, then runs the engine tests (node:test)
npm run test:browser # needs Playwright's Chromium: npx playwright install chromium
npm run demo # http://127.0.0.1:8080/demo/0BSD