There is no standard way to have a field's contents be readable while editing and obfuscated while at rest. The closest we get is the "password reveal" pattern, but that isn't as customizable for regular fields. The form-obfuscator web component enables that.
npm install @aarongustafson/form-obfuscator
Import the class and define the custom element with your preferred tag name:
import { FormObfuscatorElement } from '@aarongustafson/form-obfuscator';
// Define with default name
customElements.define('form-obfuscator', FormObfuscatorElement);
// Or define with a custom name
customElements.define('my-field-obfuscator', FormObfuscatorElement);
Use the guarded definition helper to register the element when customElements is available:
import '@aarongustafson/form-obfuscator/define.js';
If you prefer to control when the element is registered, call the helper directly:
import { defineFormObfuscator } from '@aarongustafson/form-obfuscator/define.js';
defineFormObfuscator();
You can also include the guarded script from HTML:
<script
src="./node_modules/@aarongustafson/form-obfuscator/define.js"
type="module"
></script>
You can also use the component directly from a CDN:
<script
src="https://unpkg.com/@aarongustafson/form-obfuscator@latest/define.js"
type="module"
></script>
character - The text character to replace each obfuscated character with. Default: *pattern (optional) - Regular expression to manage replacement. Matched characters will be kept, all other characters will be replaced. If no match is found, the whole string will be replaced.replacer (optional) - A custom replacement function that will be used to replace the value. Requires pattern be set as well. The obfuscated value will be a result of value.replace( pattern, replacer ) where value is the original field value, pattern is a Regular Expression conversion of pattern, and replacer is this function. All components of the replacer will need to be addressed via arguments.maxlength (optional) - The maximum number of characters to display when obfuscating the text. This truncation is applied at the end of the replacement process.This element will emit two custom JavaScript events:
form-obfuscator:hide when a field is obfuscatedform-obfuscator:reveal when a field is obfuscatedOn either event you can access the obfuscated field through the reference event.detail.field and the hidden field through the reference event.detail.hidden.
This web component makes no assumptions about markup. It will apply its logic to any text-style input elements it contains.
All field values will be duplicated into a hidden field, which is the field that will actually be submitted with the form. The source order will be such that the hidden field will be the one whose value is submitted.
<form-obfuscator>
<label for="my-field">Field Label</label>
<input id="my-field" name="foo" />
</form-obfuscator>
The component adds no palette or focus styling. It keeps authored labels and native fields in the light DOM. Without JavaScript, or if an import fails, those fields remain readable and editable; values are not obfuscated. Obfuscation is not encryption. Actual values remain available to scripts and form submission. Use fictional values in the demos, especially the event log, which displays revealed values.
Keep configuration trusted and valid. The component compiles pattern as a
regular expression and replacer as JavaScript; don’t fill those attributes
with untrusted content. A restrictive Content Security Policy may block custom
replacers.
The demos pair reading surfaces with CanvasText/Canvas, inline code,
buttons, and event output with ButtonText/ButtonFace, code blocks and
text fields with FieldText/Field, and marked passages with MarkText/Mark.
In ordinary color modes, Canvas underlays prevent transparent system surfaces
from inheriting an unrelated background. Forced colors use solid Field or
ButtonFace backplates instead, so gradient suppression does not separate
foregrounds from their intended surfaces. Supporting text inherits its surface
foreground;
only Canvas-backed supporting text uses an 80% foreground mix. Forced colors,
increased contrast, and browsers without color-mix() retain full-strength
text. Button hover adds an underline and an optional 5% foreground wash without
fading labels or boundaries. Native focus and automatic forced-color adjustment
remain intact.
On narrow screens or with enlarged text, examples stack and code blocks scroll within their column. Tab to a code block and use the arrow keys to scroll it; the browser supplies its focus indicator.
If you change these styles, test foregrounds and backgrounds together,
including inherited and transparent surfaces. System color names alone do not
guarantee contrast. Tests cover recorded study palettes and browser behavior,
not every operating-system theme or assistive technology. Bundled Ubuntu
WebKit’s dark ButtonText/ButtonFace limitation is tracked separately;
only those surface assertions use an expected-failure annotation. Field and
marked-text assertions run normally, with negative controls that verify they
reject their own contrast regressions. The tests do not reduce contrast
thresholds.
This web component works in all modern browsers that support:
For older browsers, you may need polyfills for Custom Elements.
TypeScript definitions are included with this package. You get full type support and event typings automatically when using this component in TypeScript projects.
You can place multiple text-style input elements inside a single form-obfuscator. Each input will be independently obfuscated and managed, with its own hidden field for form submission.
# Run tests
npm test
# Run tests once
npm run test:run
# Run tests with UI
npm run test:ui
# Run tests with coverage
npm run test:coverage
# Chromium, Firefox, and WebKit regressions (one worker)
npm run test:browser
# Lint code
npm run lint
# Format code
npm run format