Form Field Obfuscation Web Component

npm version CI status Minified + gzipped size License Type definitions

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.

Demos

Installation

npm install @aarongustafson/form-obfuscator

Usage

Option 1: Import the class and define manually

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);

Option 2: Auto-define the custom element (browser environments only)

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>

CDN Usage

You can also use the component directly from a CDN:

<script
	src="https://unpkg.com/@aarongustafson/form-obfuscator@latest/define.js"
	type="module"
></script>

API

Events

This element will emit two custom JavaScript events:

On either event you can access the obfuscated field through the reference event.detail.field and the hidden field through the reference event.detail.hidden.

Markup Assumptions

This web component makes no assumptions about markup. It will apply its logic to any text-style input elements it contains.

Implementation notes

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.

Example

<form-obfuscator>
	<label for="my-field">Field Label</label>
	<input id="my-field" name="foo" />
</form-obfuscator>

Demo styling and privacy

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.

Browser Support

This web component works in all modern browsers that support:

For older browsers, you may need polyfills for Custom Elements.

TypeScript Support

TypeScript definitions are included with this package. You get full type support and event typings automatically when using this component in TypeScript projects.

Multiple Input Support

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.

Development

Testing

# 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

Linting and Formatting

# Lint code
npm run lint

# Format code
npm run format