The component wraps two related form fields and adds validation to ensure they match. It’s intentionally additive, which means it works with native browser validation rather than trying to replace it.

# Wrap and go

The API is intentionally simple:

<form-matching-fields><labelfor=“password”>Password</label><inputid=“password”type=“password”required/><labelfor=“password-again”>Password again</label><inputid=“password-again”type=“password”required/></form-matching-fields>

The component evaluates the first two eligible text-type inputs it contains and applies mismatch validation to the second one when both fields have values.

# What counts as an eligible field?

To keep behavior predictable, the component only considers descendant input elements of these types:

• text
• email
• password
• search
• tel
• url

It ignores disabled and readonly controls, which helps prevent false positives when you have conditional or locked fields in the same wrapper.

# Validation behavior that plays nicely

One of the core goals here was to avoid stepping on existing validation rules. In practice, that means:

• If the second field already has a native validation issue (like required or type mismatch), this component won’t mask it.
• If the second field already has a custom validity message, this component won’t overwrite that either.
• It only clears mismatch errors that it set itself.

That last point is especially useful in larger forms where multiple constraints overlap. You don’t want one helper trying to be the sole source of truth.

# Customizing the validation message

By default, the component uses this template for the validation message:

The fields “{label_1}” and “{label_2}” should match

It smartly resolves the labels ({label_1} and {label_2}) from your markup in this order:

1. associated <label for> text
2. wrapping <label> text
3. aria-label
4. name
5. id

You can override it with the validation-message attribute:

<form-matching-fieldsvalidation-message=“Please ensure {label_2} matches {label_1}.”><labelfor=“email”>Email</label><inputid=“email”type=“email”required/><labelfor=“verify-email”>Verify email</label><inputid=“verify-email”type=“email”required/></form-matching-fields>

In most forms, that gives you a clear error message without extra setup.

# Demo

I put together a demo of the web component over on GitHub:

# Grab it

You can explore the source, file issues, and suggest enhancements in the form-matching-fields repository.

Update: This post has been refreshed to cover the component’s current loading options, throttled input behavior, accessibility model, and localization hooks.

This is a modern replacement for my old jQuery Easy Validation Rules plugin, reimagined as a web component with native form validation integration.

To get started, associate the component with an input element using the for attribute and define your validation rules:

<form><labelfor=“username”>Username:</label><inputtype=“text”id=“username”name=“username”required/><form-validation-listfor=“username”><ul><lidata-pattern=“[A-Z]+”>At least one capital letter</li><lidata-pattern=“[a-z]+”>At least one lowercase letter</li><lidata-pattern=“[\d]+”>At least one number</li></ul></form-validation-list><buttontype=“submit”>Submit</button></form>

By default, validation runs on the input event with a 250ms throttle. Matched rules get a checkmark (✓), unmatched rules get an X (✗), and while someone is typing the component announces a concise progress summary instead of repeatedly re-reading the whole rule list. When all rules match, the field is valid and the form can be submitted.

# What’s happening under the hood?

The component:

1. Associates with an input via the for attribute (just like a label element)
2. Finds all elements with data-pattern attributes
3. Tests the input value against each pattern when the configured trigger fires
4. Adds validation-matched or validation-unmatched classes and visual indicators accordingly
5. Inserts localized, visually hidden state text once the field has a value
6. Updates a single polite live region while users type
7. Uses setCustomValidity() to integrate with native form validation
8. Prevents form submission until all rules match

The cascade animation, controlled by each-delay, adds a subtle sequential effect as rules are checked. Small detail, meaningful feedback.

# Whose rules? Your rules.

Define rules using regular expression patterns in the data-pattern attribute:

<form-validation-listfor=“password”><ul><!-- Length requirements --><lidata-pattern=“.{8,}”>At least 8 characters</li><lidata-pattern=“.{8,32}”>Between 8 and 32 characters</li><!-- Character type requirements --><lidata-pattern=“[A-Z]+”>At least one uppercase letter</li><lidata-pattern=“[a-z]+”>At least one lowercase letter</li><lidata-pattern=“[\d]+”>At least one number</li><lidata-pattern=“[!@#$%^&]+“>At least one special character</li><!-- Format requirements --><lidata-pattern=”.+@.+..+“>Valid email format</li><lidata-pattern=”+$“>Only letters and numbers</li></ul></form-validation-list>

Each pattern is a standard JavaScript regular expression. The component tests the input value against all patterns on the configured trigger, using throttled input events by default.

# Input event too noisy? No worries.

By default, validation runs on the input event with a 250ms throttle. If you want immediate feedback while typing, set input-throttle="0". If you’d rather wait until the field loses focus, switch the trigger-event to "blur":

<form-validation-listfor=”email“trigger-event=”blur“><ul><lidata-pattern=”.+@.+“>Contains @ symbol</li><lidata-pattern=”.+@.+..+“>Valid email format</li></ul></form-validation-list>

With this attribute in place, validation runs immediately when the field loses focus. In this mode, input-throttle is ignored and the component keeps the full criteria list available to assistive technology while someone types.

# Wanna adjust the cascade delay? Go for it.

Use the each-delay attribute to control the delay between checking each rule. The default speed is 150ms, but you can tune it to any number of milliseconds:

<form-validation-listfor=”password“each-delay=”100“><!-- rules --></form-validation-list>

Set it to “0” to remove the cascade effect entirely and check all rules simultaneously.

# Need full design control? You got it.

If you want full design control over the component, you can absolutely have it. The whole component operates in light DOM, so your styles will pierce through. And you can customize class names for integration with CSS frameworks using a set of attributes on the form-validation-list element. The field-valid-class and field-invalid-class attributes control the class names applied to the input field itself, while the rule-matched-class and rule-unmatched-class attributes control the class names applied to each rule item.

Here’s a complete example:

<style>.is-valid{border-color: green;}.is-invalid{border-color: red;}.rule-pass{color: green;}.rule-fail{color: red;}</style><form-validation-listfor=”username“field-valid-class=”is-valid“field-invalid-class=”is-invalid“rule-matched-class=”rule-pass“rule-unmatched-class=”rule-fail“><ul><lidata-pattern=”.{5,}“>At least 5 characters</li><lidata-pattern=”[!@#]+">Special char (!@#)</li></ul></form-validation-list>

This approach lets you use class names that match your existing CSS architecture instead of making one small component dictate terms to the rest of your styles.

You can also override the per-instance icon glyphs with the rule-matched-icon and rule-unmatched-icon attributes, or control the shared visual styling using CSS custom properties:

• –rule-matched-icon - Content for matched state (default: “✓”)
• –rule-unmatched-icon - Content for unmatched state (default: “✗”)
• –rule-icon-size - Size of icons (default: 1em)
• –rule-matched-color - Color for matched rules (default: green)
• –rule-unmatched-color - Color for unmatched rules (default: red)

The older –validation- custom property names are still supported as legacy aliases.

Here’s an example of that:

form-validation-list{–rule-matched-icon:”✅“;–rule-unmatched-icon:”❌“;–rule-icon-size: 1.2em;–rule-matched-color: #28a745;–rule-unmatched-color: #dc3545;}

# TypeScript or framework project? You’re covered.

The package now ships with bundled type definitions and reflects its core properties and attributes in both directions. That makes it a much better fit for TypeScript, JSX, SSR, and declarative framework setups where properties may be assigned before the custom element upgrades.

# Bit of a control freak? There’s an API.

If you really want to get into the weeds, you can also listen for validation changes in your JavaScript code:

const validationList = document.querySelector(“form-validation-list”);validationList.addEventListener(“form-validation-list:validated”,(event)=>{const{ isValid, matchedRules, totalRules, field }= event.detail;console.log(</span><span class="token string">Matched </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>matchedRules<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> of </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>totalRules<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> rules</span><span class="token template-punctuation string">);console.log(</span><span class="token string">Field is </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>isValid <span class="token operator">?</span> <span class="token string">"valid"</span> <span class="token operator">:</span> <span class="token string">"invalid"</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">);});

The event fires after validation completes and gives you the current state. Nice and tidy.

You can also manually trigger validation and check the element’s current state at any time:

const validationList = document.querySelector(“form-validation-list”);// Trigger validationconst isValid = validationList.validate();console.log(“Is valid:”, isValid);// Check current stateconsole.log(“Current state:”, validationList.isValid);

# Global site? Relájese.

If you need the component to work in different languages, that’s totally doable. You can customize three separate pieces of copy: the browser validation message (validation-message), the live summary announced while typing (announcement), and the per-rule hidden status text (rule-matched-alt and rule-unmatched-alt). All of the message templates support the {matched} and {total} placeholders:

<!-- Spanish --><form-validation-listfor=”contrasena“announcement=”{matched} de {total} criterios cumplidos“rule-matched-alt=”Criterio cumplido“rule-unmatched-alt=”Criterio pendiente“validation-message=”Por favor, cumple todos los requisitos ({matched} de {total})“><ul><lidata-pattern=”[A-Z]+“>Al menos una letra mayúscula</li><lidata-pattern=”[a-z]+“>Al menos una letra minúscula</li><lidata-pattern=”[\d]+“>Al menos un número</li></ul></form-validation-list><!-- French --><form-validation-listfor=”mot-de-passe“announcement=”{matched} critères satisfaits sur {total}“rule-matched-alt=”Critère satisfait“rule-unmatched-alt=”Critère non satisfait“validation-message=”Veuillez satisfaire à toutes les exigences ({matched} sur {total})“><ul><lidata-pattern=”[A-Z]+“>Au moins une lettre majuscule</li><lidata-pattern=”[a-z]+“>Au moins une lettre minuscule</li><lidata-pattern=”[\d]+“>Au moins un chiffre</li></ul></form-validation-list>

# Is it a progressive enhancement? Heck yeah!

The component uses light DOM, so if JavaScript fails, users still see the validation requirements as a standard list. They can read what is expected even without the visual feedback. Your server-side validation still does the important enforcement work regardless… right? Right?

# Is it screen reader accessible? Yep.

The component is built with accessibility in mind:

• Proper description support: The validation list is automatically associated with the input via aria-describedby, and if the field already has aria-describedby, the original value is preserved.
• A concise announcement model: With the default trigger-event="input", the component temporarily suspends the full criteria list from aria-describedby while someone types and uses a single polite live region to announce progress instead.
• State restoration on blur: When focus leaves the field, any pending validation timeouts are cleared and the full criteria list is restored so returning to the field announces the final criteria state.
• Localized rule state: Once the field has a value, each rule gets visually hidden localized state text in the DOM, which is more robust than relying on CSS-generated content alone.

If you have suggestions for other ways to improve the accessibility of this component, please open an issue on GitHub.

# Does it integrate with the browser’s validation engine? Naturally.

The component uses setCustomValidity() to participate in native form validation:

• When all rules match, custom validity is cleared
• When rules don’t match, a custom validity message is set
• Form submission is prevented until all rules pass
• Works with :valid and :invalid CSS pseudo-classes
• Compatible with the Constraint Validation API

const form = document.querySelector(“form”);const field = document.getElementById(“username”);form.addEventListener(“submit”,(e)=>{if(!form.checkValidity()){e.preventDefault();console.log(“Validation failed:”, field.validationMessage);}});

# Here’s a real-world example

Here’s a complete password validation setup:

<form><labelfor=”password“>Password:</label><inputtype=”password“id=”password“name=”password“required/><form-validation-listfor=”password“><ul><lidata-pattern=”.{8,}“>At least 8 characters</li><lidata-pattern=”[A-Z]+“>At least one uppercase letter</li><lidata-pattern=”[a-z]+“>At least one lowercase letter</li><lidata-pattern=”[\d]+“>At least one number</li><lidata-pattern=”[!@#$%^&]+">At least one special character (!@#$%^&)</li></ul></form-validation-list><buttontype=“submit”>Submit</button></form>

Users see exactly which requirements they have met, and which they still need to satisfy. That is usually a lot kinder than springing the whole list on them after submit.

# Play with it

Check out the demo with various examples:

# Grab it

View the project on GitHub.

Install via npm:

npminstall @aarongustafson/form-validation-list

For most projects, import the guarded auto-definition helper:

import“@aarongustafson/form-validation-list/define.js”;

If you want to control the tag name yourself, import FormValidationListElement and register it manually.

If you give it a spin, I’d love to hear how it works in your forms. Happy validating!

At its core, form-saver is a small web component that wraps a form, keeps an eye on it, stores values in localStorage, and restores them when the page loads again. Better yet, it clears out saved data after a successful submission so you’re not accidentally resurrecting stale information the next time someone stops by. Nobody wants yesterday’s half-finished support request shambling back to life.

# Basic usage

All you need to do is wrap your form in the component:

<form-saver><formaction=“/contact”method=“post”><label>Name<inputname=“name”autocomplete=“name”/></label><label>Email<inputname=“email”type=“email”autocomplete=“email”/></label><label>Message<textareaname=“message”></textarea></label><buttontype=“submit”>Send</button></form></form-saver>

That’s it. The component targets the first descendant form, saves values as people type or make changes, and restores them when they come back. No extra plumbing, just a form with a slightly better memory than most of us before coffee. Depending on the day, that may not be a terribly high bar, but still.

This is especially handy for forms that are a little more involved than a simple email signup. Job applications, checkout flows, support requests, and multi-question onboarding forms all benefit from a little resilience. So do the people filling them out, who generally have better things to do than retype the same answers because a tab got squirrelly.

# What actually gets saved?

form-saver supports the controls most of us reach for every day:

• Text-style input fields
• textarea elements,
• select elements (including multi-selects), and
• checkbox and radio controls.

File inputs are intentionally excluded.

Because the component works in light DOM, your form remains your form. Your labels, validation, layout, and CSS continue to work exactly as they did before. form-saver just adds a bit of memory and, ideally, cuts down on a few muttered curses.

# Want to keep a few fields after submit?

In many cases, clearing everything after a successful submission is the right call. Sometimes, though, it makes sense to keep a few details around. Maybe you want to preserve a visitor’s name and email address on a contact form while clearing the message body. That way they do not have to keep retyping the boring bits. Nobody wakes up excited to enter their email address for the fourth time.

That is what the retain attribute is for:

<form-saverretain=“name email”><formaction=“/contact”method=“post”>…</form></form-saver>

After a successful submission, name and email stick around, but message gets cleared. Simple, sensible, and less likely to leave someone staring at your form like it just read their credit card number aloud in a bus station.

# Better yet, let users decide

Persisting form data can be incredibly helpful, but there is a human side to this. Just because we can keep someone’s information around doesn’t mean we should do it without asking. That is where retain-choice comes in: it lets you be useful without being presumptuous.

Add it alongside retain and form-saver will inject an opt-in checkbox for the user. Nice and easy:

<form-saverretain=“name email”retain-choiceretain-choice-label=“Store my contact information for later”><formaction=“/contact”method=“post”>…</form></form-saver>

By default, that checkbox is inserted just before the first submit control. If the user leaves it unchecked, the retained fields are cleared along with everything else after submit. If they opt in, those selected fields remain. Their call, as it should be.

Need to place that control somewhere more appropriate in your layout? Use retain-choice-container to point to a CSS selector:

<form-saverretain=“name email”retain-choiceretain-choice-label=“Remember my details next time”retain-choice-container=“.form-footer”><formaction=“/contact”method=“post”>…<divclass=“form-footer”><buttontype=“submit”>Send</button></div></form></form-saver>

That gives you a lot more control over the experience without making you build the retention UI yourself.

# Need a custom storage key?

By default, form-saver derives its storage key from the wrapped form’s method and action, which is usually exactly what you want. It keeps different forms from stepping on one another and keeps the setup nice and boring. Boring is good.

If you need something more explicit, you can provide your own storage-key:

<form-saverstorage-key=“checkout:shipping-address”><formaction=“/checkout/shipping”method=“post”><label>Street Address<inputname=“street-address”autocomplete=“street-address”/></label><label>Postal Code<inputname=“postal-code”autocomplete=“postal-code”/></label><buttontype=“submit”>Continue</button></form></form-saver>

This is useful when a form’s URL is not stable, or when you want multiple views to intentionally share the same saved state.

# Want to drive it yourself?

If you need more direct control, the component exposes a few methods:

const saver = document.querySelector(“form-saver”);// Persist the current statesaver.saveFormState();// Restore previously saved valuessaver.restoreFormState();// Clear out anything stored for this formsaver.clearSavedData();

That can be useful when you want to pair it with your own UI, analytics, or custom workflow around save and restore.

# Progressive enhancement, as usual

This component follows a pattern I am always going to favor: start with a perfectly ordinary form, then layer on the enhancement. If JavaScript fails, the form still works. Users can still fill it out and submit it. They just will not get the recovery behavior. Annoying, perhaps, but not catastrophic. And that is very much the point.

That’s a pretty good trade-off.

And because saved values are only cleared after a successful submit flow, you do not lose everything just because client-side validation blocked submission or some other script got clever at exactly the wrong moment. That matters. A lot of “smart” form experiences are only smart right up until they are not.

# Demo

If you want to kick the tires, I put together a live demo with examples of the retention options as well:

# Grab it

The project is available on GitHub, and you can install it from npm:

npminstall @aarongustafson/form-saver

If you want the easiest path, just import it and let the component register itself:

import“@aarongustafson/form-saver”;

If you would rather define it yourself, you can import the class directly:

import{ FormSaverElement }from“@aarongustafson/form-saver/form-saver.js”;customElements.define(“form-saver”, FormSaverElement);

Either way, you wind up with a more forgiving form experience and a little less needless frustration for the people filling it out. Which, in my book, is a pretty solid deal. The bar for delight in forms is often just “don’t make me do that again,” and honestly, I’ll take it.

All you need to do is provide a single field group and the component handles the rest:

<form><form-repeatable><div><labelfor=“stop-1”>Stop 1</label><inputid=“stop-1”type=“text”name=“stops[]”></div></form-repeatable></form>

The form-repeatable component treats its first child as a template and injects a button that allows users to repeat the field. When users click “Add Another” (the default “add” button text), the following happens:

1. The template is cloned,
2. Any numbers are auto-incremented (“Stop 1” → “Stop 2”, stop-1 → stop-2),
3. A new group is added to the component,
4. A “remove” button is added when there’s more than the minimum number of groups (1 by default), and
5. Form values update automatically via ElementInternals.

That last piece is crucial. The plugin is a fully-participating member in the parent form:

• All inputs are collected and submitted automatically
• Values are added to FormData
• In-built form reset is respected
• A form’s disabled state is respected

No special handling required; it works like a native form control.

# Need customized buttons? You bet!

If you don’t like the default text, or your site is in another language, you can define your own button labels using the add-label and remove-label attributes:

<form-repeatableadd-label=“Add Another Item”remove-label=“Delete”><div><labelfor=“item-1”>Item 1</label><inputid=“item-1”type=“text”name=“items[]”/></div></form-repeatable>

With that simple change, the add button reads “Add Another Item” and each remove button reads “Delete”. To improve the experience for screen reader users, the remove-label value is combined with the associated label/legend to create accessible names like “Delete Item 1” which is far more helpful.

# Already have values to show? No problem.

If your form needs to start with multiple groups already filled in, just provide them as child elements:

<form><form-repeatablemin=“2”><div><labelfor=“phone-1”>Phone 1</label><inputid=“phone-1”type=“tel”name=“phones[]”value=“555-0100”></div><div><labelfor=“phone-2”>Phone 2</label><inputid=“phone-2”type=“tel”name=“phones[]”value=“555-0101”></div><div><labelfor=“phone-3”>Phone 3</label><inputid=“phone-3”type=“tel”name=“phones[]”></div></form-repeatable></form>

All child elements become managed groups, and existing values are preserved. Perfect progressive enhancement!

# Need to do something more complex? I got you.

You’re not limited to repeating a single field. Each group can contain multiple, related fields. Here’s an example with a fieldset for guest information:

<form-repeatable><fieldset><legend>Guest 1</legend><labelfor=“guest-name-1”>Name</label><inputid=“guest-name-1”type=“text”name=“guest-name-1”><labelfor=“guest-email-1”>Email</label><inputid=“guest-email-1”type=“email”name=“guest-email-1”></fieldset></form-repeatable>

When the component initializes, the whole fieldset becomes the template. As users add guests, numeric values in text and attributes increment automatically. In this example, that means the legend, for, id, and name values all stay in sync.

# Need to constrain the responses? Sure thing.

Use the min and max attributes to control the number of allowed groups:

<form-repeatablemin=“2”max=“5”add-label=“Add Team Member”remove-label=“Remove”><div><labelfor=“member-1”>Team Member 1</label><inputid=“member-1”type=“text”name=“members[]”/></div></form-repeatable>

This creates a component that:

• Starts with 1 member,
• Requires adding new members until the min threshold (2) is met,
• Cannot have fewer than 2 team members,
• Cannot have more than 5 team members, and
• Uses custom button labels.

The remove buttons are not shown when at the minimum threshold (1 by default) and the add button disappears when you hit the maximum.

# Prefer an explicit template? Bring it!

This component can accept a template element containing the fields you want to repeat. Just drop in {n} placeholders where you want the sequential numbers to appear:

<form-repeatable><template><div><labelfor=“email-{n}”>Email {n}</label><inputid=“email-{n}”type=“email”name=“emails[]”></div></template></form-repeatable>

When hoisted into the component, the template element is removed from the light DOM and used internally.

# Here’s what you need to know about styling it

The component uses Shadow DOM to encapsulate its internal structure, but you can style it using CSS parts and custom properties. It also adopts your global styles automatically.

The component uses CSS Grid by default:

• Two columns: Content in column 1, remove buttons aligned inline end in column 2
• Subgrid: Each group uses subgrid to align with parent grid
• Add button: Appears below all groups

You can use CSS parts to style the buttons and field groups. Here are some examples:

/* Style all buttons /form-repeatable::part(button){padding: 0.5rem 1rem;border-radius: 4px;cursor: pointer;}/ Style the add button /form-repeatable::part(add-button){background: #28a745;color: white;}/ Style remove buttons /form-repeatable::part(remove-button){background: #dc3545;color: white;}/ Customize the grid layout /form-repeatable::part(groups){grid-template-columns: 1fr auto;gap: 1rem;}/ Style each group */form-repeatable::part(group){padding: 1rem;background: #f8f9fa;border-radius: 4px;margin-bottom: 0.5rem;}

Available parts:

• groups - Container for all groups (CSS grid by default)
• group - Each repeatable group wrapper
• content - Container for group’s fields
• group-controls - Container for the remove button
• controls - Container for the add button
• button - All buttons
• add-button - The add button
• remove-button - All remove buttons

# Want to hook into changes? You’re extra, but sure.

You can listen for when groups are added or removed and run your own custom code:

const repeatable = document.querySelector(“form-repeatable”);repeatable.addEventListener(“form-repeatable:added”,(event)=>{console.log(“Group added. Total groups:”, event.detail.groupCount);});repeatable.addEventListener(“form-repeatable:removed”,(event)=>{console.log(“Group removed. Total groups:”, event.detail.groupCount);});

# Go with the progressive enhancement flow

If JavaScript fails, users still see the initial field group(s) and can complete the form. They won’t be able to add more, but nothing breaks. Set your minimums accordingly.

# Demo

Explore the demo with various examples:

# Grab it now

Check out the project on GitHub. Install via npm:

npminstall @aarongustafson/form-repeatable

Import and go:

import“@aarongustafson/form-repeatable”;

This single component manages repeatable field groups with native form participation, no framework required.

The Web Component Starter Template is based on architecture and patterns I’ve refined across recent projects. It incorporates Google’s Custom Element Best Practices and advice from other web component practitioners, including the always-brilliant Dave Rupert.

# What’s included

The template includes most everything you need to ship a production-ready web component:

• Interactive setup wizard that scaffolds everything for your component.
• Multiple import patterns supporting both auto-define and manual registration.
• Demo pages for development, documentation, and CDN examples.
• Code quality tools including ESLint and Prettier with sensible defaults.
• Modern testing setup with Vitest, Happy DOM, and coverage reporting.
• CI/CD workflows for GitHub Actions with automated testing and npm publishing.
• Publishing ready with proper npm package configuration and OIDC support.

# Quick start with interactive setup

Getting started is straightforward. If you’re a GitHub user, you can create a new repository directly from the template. Alternatively, clone it locally:

git clone https://github.com/aarongustafson/web-component-starter.git my-componentcd my-componentnpminstallnpm run setup

The setup wizard asks for your component name and description, then automatically:

• Renames all files based on your component name,
• Updates all code and configuration templates with your details,
• Generates a proper README from the included template,
• Cleans up all template-specific files, and
• Initializes the git repository.

You’re left with a fully scaffolded repository, ready for you to develop your component.

# Flexible import patterns

One of the key features is support for multiple registration patterns. Folks can choose what works best for them:

Manual registration for full control:

import{ ComponentNameElement }from‘@yourscope/component-name’;customElements.define(‘my-custom-name’, ComponentNameElement);

Auto-define for convenience:

import‘@yourscope/component-name/define.js’;

Or call the helper directly:

import{ defineComponentName }from‘@yourscope/component-name/define.js’;defineComponentName();

The auto-define approach includes guards, so it only runs in browser environments and only when customElements is available. That keeps it safe for server-side rendered (SSR) scenarios.

# Testing made easy

The template includes a comprehensive testing setup using Vitest:

import{ describe, it, expect }from‘vitest’;describe(‘MyComponent’,()=>{it(‘should render’,()=>{const el = document.createElement(‘my-component’);expect(el).toBeInstanceOf(HTMLElement);});});

Happy DOM provides a lightweight browser environment, and the included scripts support:

• Watch mode for development: npm test
• Single run for CI: npm run test:run
• Interactive UI: npm run test:ui
• Coverage reports: npm run test:coverage

# Automated publishing with OIDC

The template is configured for secure automated publishing to npm using OpenID Connect (OIDC), which is more secure than long-lived tokens. After you manually publish the first version and configure OIDC on npm, create a GitHub release and the workflow handles publishing automatically.

Manual publishing is still supported if you prefer that approach.

# Following best practices

The template bakes in best practices from the start:

• Shadow DOM with proper encapsulation
• Custom Elements v1 API
• Reflection of properties to attributes
• Lifecycle callbacks used appropriately
• Accessible patterns and ARIA support
• Progressive enhancement approach

The included WEB-COMPONENTS-BEST-PRACTICES.md document explains the reasoning behind each pattern, making it a learning resource as well as a starter template.

# Why I built this

After creating components like form-obfuscator, tabbed-interface, and several others, I kept copying and adapting the same project structure. This template captures those patterns so I—and now you—can start faster without skipping the fundamentals.

If you build something with it, I’d love to hear about it!

This component is a modern replacement for my old jQuery predictive typing plugin. I’ve reimagined it as a standards-based web component.

# Basic usage

To use the component, wrap it around your input field and specify an endpoint:

<dynamic-datalistendpoint=“/api/search”><labelfor=“search”>Search<inputtype=“text”id=“search”name=“search”placeholder=“Type to search…”/></label></dynamic-datalist>

As users type, the component makes GET requests to that endpoint, passing in the typed value as the “query” parameter (e.g., /api/search?query=WHAT_THE_USER_TYPED). The response from the endpoint is used to populates a dynamic datalist element with the results.

The structure of the response should be JSON with an options array of string values:

{“options”:[“option 1”,“option 2”,“option 3”]}

# How it works

Under the hood, the component:

1. Adopts (or creates) a datalist element for your input,
2. Listens for “input” events,
3. Debounces requests (waiting at least 250ms) to avoid overwhelming your API,
4. Sends requests to your endpoint with the current value of the input,
5. Reads back the JSON response,
6. Updates the datalistoption elements, and
7. Dispatches the update event.

All of this happens transparently—users just see autocomplete suggestions appearing as they type.

# Need POST?

You can change the submission method via the method attribute:

<dynamic-datalistendpoint=“/api/lookup”method=“post”><labelfor=“lookup”>Lookup<inputtype=“text”id=“lookup”name=“lookup”/></label></dynamic-datalist>

This sends a POST request with a JSON body: { "query": "…" }. Currently GET and POST are supported, but I could add more if folks want them.

# Custom variable names

As I mentioned, the component uses “query” as the parameter name by default, but you can easily change it via the key attribute:

<dynamic-datalistendpoint=“/api/terms”key=“term”><labelfor=“search”>Term search<inputtype=“text”id=“search”name=“term”/></label></dynamic-datalist>

This sends the GET request /api/terms?term=….

# Working with existing datalists

If your input already has a datalist defined, the component will inherit it and replace the existing options with the fetched results, which makes for a nice progressive enhancement:

<dynamic-datalistendpoint=“/api/cities”><labelfor=“city”>City<inputtype=“text”id=“city”list=“cities-list”placeholder=“Type a city…”/></label><datalistid=“cities-list”><option>New York</option><option>Los Angeles</option><option>Chicago</option></datalist></dynamic-datalist>

Users see the pre-populated cities immediately, and as they type, API results supplement the list. If JavaScript fails or the web component doesn’t load, users still get the static options. Nothing breaks.

# Event handling

If you want to tap into the component’s event system, it fires three custom events:

• dynamic-datalist:ready - Fired when the component initializes
• dynamic-datalist:update - Fired when the datalist is updated with new options
• dynamic-datalist:error - Fired when an error occurs fetching data

const element = document.querySelector(“dynamic-datalist”);element.addEventListener(“dynamic-datalist:ready”,(e)=>{console.log(“Component ready:”, e.detail);});element.addEventListener(“dynamic-datalist:update”,(e)=>{console.log(“Options updated:”, e.detail.options);});element.addEventListener(“dynamic-datalist:error”,(e)=>{console.error(“Error:”, e.detail.error);});

Each event provides helpful detail objects with references to the input, datalist, and other relevant data.

# Demo

Check out the demo for live examples (there are also unpkg and ESM builds if you want to test CDN delivery):

# Grab it

The project is available on GitHub. You can also install via npm:

npminstall @aarongustafson/dynamic-datalist

If you go that route, there are a few ways to register the element depending on your build setup:

# Option 1: Define it yourself

import{ DynamicDatalistElement }from“@aarongustafson/dynamic-datalist”;customElements.define(“dynamic-datalist”, DynamicDatalistElement);

# Option 2: Let the helper guard registration

import“@aarongustafson/dynamic-datalist/define.js”;// or, when you need to wait:import{ defineDynamicDatalist }from“@aarongustafson/dynamic-datalist/define.js”;defineDynamicDatalist();

# Option 3: Drop the helper in via a <script> tag

<scriptsrc=“./node_modules/@aarongustafson/dynamic-datalist/define.js”type=“module”></script>

Regardless of how you register it, there are no framework dependencies—just clean autocomplete powered by your API. As I mentioned, it’s also available via CDNs, such as unpkg too, if you’d prefer to go that route.

# Basic usage

Wrap any text field in the component and it will automatically obfuscate the value when the field loses focus:

<form-obfuscator><labelfor=“secret-key-1”>What was your first pet’s name?</label><inputtype=“text”id=“secret-key-1”name=“secret-key-1”/></form-obfuscator>

When users click into the field, they see the actual value. When they click away, it’s replaced with asterisks (). The real value is preserved in a hidden field for form submission.

# Custom obfuscation characters

If you don’t like asterisks, you can specify any character you like:

<form-obfuscatorcharacter=“•”><labelfor=“account”>Account Number</label><inputtype=“text”id=“account”name=“account”/></form-obfuscator>

Or get creative:

<form-obfuscatorcharacter=“🤐”><labelfor=“ssn”>Social Security Number</label><inputtype=“text”id=“ssn”name=“ssn”/></form-obfuscator>

# Pattern-based obfuscation

Sometimes you want to show part of the value while hiding the rest. The pattern attribute lets you specify which characters to keep visible:

<form-obfuscatorpattern=“\d{4}$”><labelfor=“ssn”>Social Security Number</label><inputtype=“text”id=“ssn”name=“ssn”/></form-obfuscator>

This keeps the last four digits visible while replacing everything else with your obfuscation character. Perfect for Social Security Numbers, credit cards, or phone numbers where showing the last few digits helps users confirm they’ve entered the right value.

# Limiting displayed characters

Use the maxlength attribute to cap how many characters appear when obfuscated:

<form-obfuscatormaxlength=“4”><labelfor=“password”>Password</label><inputtype=“text”id=“password”name=“password”/></form-obfuscator>

Even if the user enters a 20-character value, only four asterisks will be displayed when the field is obfuscated. This prevents giving away information about the length of the information entered.

# Custom replacement functions

For complete control, you can provide a JavaScript function via the replacer attribute:

<script>window.emailReplacer=function(){var username = arguments[0][1];var domain = arguments[0][2];return username.replace(/./g,"“)+ domain;};</script><form-obfuscatorpattern=”^(.?)(@.+)$“replacer=”return emailReplacer(arguments)“><labelfor=”email“>Email Address</label><inputtype=”text“id=”email“name=”email“value=”user@example.com“/></form-obfuscator>

This example uses a pattern to separate the username from the domain, then obfuscates only the username portion, leaving @example.com visible.

Here’s another practical example for credit cards:

<script>functioncardNumberReplacer(){var beginning = arguments[0][1];var final_digits = arguments[0][2];return beginning.replace(/\d/g,”“)+ final_digits;}</script><form-obfuscatorpattern=”^((?:[\d]+-)+)(\d+)$“replacer=”return cardNumberReplacer(arguments)“><labelfor=”cc“>Credit Card</label><inputtype=”text“id=”cc“name=”cc“value=”1234-5678-9012-3456“/></form-obfuscator>

This displays as --****-3456, showing only the last group of digits.

# Combining attributes

You can combine these attributes for sophisticated obfuscation patterns:

<form-obfuscatorpattern=”\d{4}$“character=”•“maxlength=”16“><labelfor=”card“>Credit Card</label><inputtype=”text“id=”card“name=”card“/></form-obfuscator>

This keeps the last 4 digits visible, uses bullets for obfuscation, and limits the display to 16 characters total.

# Event handling

The component dispatches custom events when values are hidden or revealed:

const obfuscator = document.querySelector(“form-obfuscator”);obfuscator.addEventListener(“form-obfuscator:hide”,(e)=>{console.log(“Field obfuscated:”, e.detail.field.value);});obfuscator.addEventListener(“form-obfuscator:reveal”,(e)=>{console.log(“Field revealed:”, e.detail.field.value);});

You can access both the visible field and the hidden field through event.detail.field and event.detail.hidden respectively.

# How it works

The component creates a hidden input field to store the actual value for form submission. When the visible field loses focus, it:

1. Copies the current value to the hidden field
2. Applies your obfuscation rules to create the display value
3. Updates the visible field with the obfuscated value
4. Dispatches the form-obfuscator:hide event

When the field gains focus, it:

1. Restores the real value from the hidden field
2. Updates the visible field
3. Dispatches the form-obfuscator:reveal event

The source order ensures the hidden field is the one that gets submitted with the form.

# Progressive enhancement

The component makes no assumptions about your markup—it works with any text-style input element. If JavaScript fails to load, the field behaves like a normal input, which is exactly what you want. Users can still enter and submit values; they just won’t get the obfuscation behavior.

# Demo

I’ve created a comprehensive demo page showing the various configuration options over on GitHub:

# Grab it

Check out the full project over on GitHub or install via npm:

npminstall @aarongustafson/form-obfuscator

Import and use:

import”@aarongustafson/form-obfuscator";

No dependencies, just a straightforward way to add field obfuscation to your forms.

ARIA Notify is an ergonomic and predictable way to tell assistive technologies (ATs), such as screen readers, exactly what to announce to users and when.

In its simplest form, developers can call the ariaNotify() method with the text to be announced to the user.

Here’s what it looks like:

// Dispatch a normal priority notificationdocument.ariaNotify(“Background task completed”,{priority:“normal”});

I’m particularly excited by this because of how much it simplifies the update process for engineers. Previously they needed to manage upates to an aria-live DOM node with the appropriate announcement level and hope for the best. This approach was plagued with issues ranging from lag — because, DOM manipulation — to confusion between whether “polite” or “assertive” was the right choice.

The ARIA Notify proposal is clear, concise, and far more likely to get used and — more importantly — used properly.

It’s currently in Origin Trial. Please give your feedback so we can get this into every browser sooner rather than later.

When one approach becomes “how things are done,” we unconsciously defend it even when standards would give us a healthier, more interoperable ecosystem. Psychologists call this reflex System Justification. Naming it helps us steer toward a standards-first future without turning the discussion into a framework war.

This whole piece is an excellent discussion about how tools can become an identity and why that’s a bad thing.

# The CSS Setup

The theming of this particular project uses CSS custom properties. For simplicty I’m going to set up two named colors and then use two theme-specific custom properties to apply them in the default light theme and the dark theme:

:root{–color-dark: #222;–color-light:rgba(255, 255, 255, 0.5);–color-background:var(–color-light);–color-foreground:var(–color-dark);}@media(prefers-color-scheme: dark){:root{–color-background:var(–color-dark);–color-foreground:var(–color-light);}}

# Applying the Theme to Canvas

To get the theme into my canvas-related code, I set up a theme object to hold the values:

const theme ={};

Next, I wrote a function to pull in the theme colors using window.getComputedStyle(). After defining the function, I call it immediately to populate the theme object:

functionimportTheme(){theme.foreground =window.getComputedStyle(document.documentElement).getPropertyValue(“–color-foreground”).trim()||“black”;theme.background =window.getComputedStyle(document.documentElement).getPropertyValue(“–color-background”).trim()||“white”;}importTheme();

I set this up with just two theme colors, but you can import as many (or few) as you like. Be sure to set a sensible default or fallback for each color though, just in case your theme’s custom property names change.

With this in place, I can set my canvas animation’s colors by referencing them from the theme object. For example:

context.fillStyle = theme.foreground;

# Keeping Things in Sync

The final bit of magic comes when you add an event listener to a MediaQueryList:

const mediaQuery = window.matchMedia(“(prefers-color-scheme: dark)”);mediaQuery.addEventListener(“change”, importTheme);

Here I’ve used matchMedia() to get a MediaQueryList object. Typically we use the matches property of this object to establish whether the media query currently matches or not. A lesser-known option, however, is that you can attach an event listener to it that will be triggered whenever the query’s status changes. So cool! With this in place, the canvas contents will update whenever the user’s theme changes. Here’s an example of that:

# Demo

I put together a quick demo of this in a fork of Alvin Shaw’s Canvas Sine Wave Experiment:

Hopefully this is helpful to someone out there. Happy theming!

You know what framework I want to use? I want a framework that aligns with the platform, not one that replaces it. I want a framework that values incremental innovation over user lock-in. I want a framework that says it’s OK to break things if it means making the Web a better place for everyone. Yes, that comes at a cost, but almost every good investment does, and I would argue that cost will be less expensive than learning a new framework and rebuilding buttons for the umpteenth time.

The form-required-if web component, which is based on a jQuery plugin I’d written in 2012, looks like this:

<form-required-ifconditions=“email=“><label>Required if there’s an email value<inputname=”depends-on-email"/></label></form-required-if>

You wrap any field (and its label) in the component and then declare the conditions under which it should be required in the conditions attribute.

# Defining the requirement conditions

Each condition is a key/value pair where the key aligns to the name of the field you need to observe and the value is the value that could trigger the dependency. If any value should trigger the dependency, you use an asterisk () as the value. In the example above, the field will become required when any value is assigned to the field matching [name="email"].

This conditions attribute can be populated with as many or as few dependencies as make sense for your use case. Multiple conditions are separated by double vertical pipes (|| a.k.a. or) as in this example:

<form-required-ifconditions=”email=||test=3“><label>Depends on email or test field<inputname=”depends-on-email-or-test“/></label></form-required-if>

Here the field depends on one of the following conditions being true:

1. the field matching [name="email"] has a value, or
2. the field matching [name="test"] has a value of “3”

If the field you reference doesn’t exist, no errors will be thrown, it will just quietly exit.

# Visually indicating a field is required

If you typically use an asterisk or similar to indicate a field is required, this web component can support that through one or both of the following attributes:

• indicator - This attribute is where you define the indicator itself. It could be something as simple as a string (e.g., ), or even full-blown HTML.
• indicator-placement - As you can probably guess, this attribute is used to set the position of the indicator. If you want it at the start of the label text, you give it the value “before.” If you want it after the text, you use “after” or don’t use the attribute at all. Indicators will be placed after the label text by default.

Here’s an example with a custom indicator that is HTML:

<form-required-ifconditions="email=”indicator="<b></b>“><label>Depends on email<inputname=”dep2"/></label></form-required-if>

If you don’t include markup in your indicator, it will be automatically wrapped in span when injected into the DOM. The hidden and aria-hidden attributes are used to toggle its visibility, relative to the requirement state of the field.

# Demo

I put together a comprehensive demo of the web component over on GitHub:

# Grab It

You can view the entire project (and suggest enhancements) over on the form-required-if component’s Github repo.

The incident was caused when a bug in CrowdStrike’s code made it out into production. The results were catastrophic: It caused roughly 8.5 million servers to crash. Hospitals weren’t able to serve the people that needed them. Airline passengers were stranded. People couldn’t access their money in banks. Folks in distress could not get the emergency services they needed. On top of that, the financial fallout is estimated to be somewhere around US$10 billion.

Bugs happen. I’d hate to be the person who was responsible for that particular bug (or the people in the quality assurance team that should have caught it), but the reality is that none of us who write code write perfect code. We all make mistakes and sometimes those mistakes make it into production. Other times, the code we write works perfectly during development and testing, but causes an unexpected issue in production. Sometimes only in very specific “edge case” circumstances that we didn’t have the foresight to consider.

Which brings me to the lesson I took away from the CrowdStrike incident: minimize the impact dependencies can have on your customers’ ability to complete critical tasks. In other words, develop dependency awareness.

The web is a hostile operating environment. Sometimes network connections are slow to resolve or time out completely, which may cause issues with your JavaScript, may result in broken images or videos, or could make it so your user never receives your CSS. Sometimes 3rd party scripts ship bugs that can hose your site completely. Sometimes a customer’s browser plugin can wreak havoc on your site by adjusting markup or injecting code. If any (or all) of those things were to happen, could your customers still accomplish their key tasks? Could they even understand your site at all?

This is why it’s so critical to start with a fully-functional website that relies only on semantic, accessible HTML and regular ol’ links and form submissions. They aren’t sexy, but they’re solid. Then progressively enhance that experience to improve things when the CSS is downloaded. And improve some more when your JavaScript executes properly. Build an awareness for the kinds of dependencies you have in your code so you can ensure there is always a fallback.

When I think about building robust websites like this, I often think of the Chrysler Imperial. The 1964-1966 model is one of the few cars that has been outright banned from entering demolition derby events. It is just too well built. It just takes the hits and keeps on driving. We should aspire to that kind of resilience in the websites we build.

Bugs happen. Can your site withstand them? Or will you let the failure of a single dependency (a.k.a., site fragility) ruin your customers’ day?

https://www.youtube.com/watch?v=-9GGDOUDLhc&start=7&end=17

# Markup Assumptions

Before I tuck into the details, I’ll start by saying that the web component begins with the assumption that you are following best practices with respect to form markup:

• Your checkbox group should be in a fieldset with a legend
• All of the checkbox elements must have the same name (e.g., “foo[]”).

In other words, they should look something like this:

<fieldset><legend>Group 1 label</legend><ul><li><label><inputtype=“checkbox”name=“foo[]”value=“1”/>First item</label></li><li><label><inputtype=“checkbox”name=“foo[]”value=“2”/>Second item</label></li><!-- options continue --></ul></fieldset>

To use the web component, you wrap the group in a form-required-checkboxes element and then include the JavaScript to initialize it.

<form-required-checkboxes><fieldset><legend>Group 1 label</legend><!-- etc. --></fieldset></form-required-checkboxes><!-- at the end of your document --><scriptsrc=“/js/web-components/form-required-checkboxes.js”async></script>

If you’re following right along, there’s an error waiting for you in the console — we need to set the requirement rules.

# The API

The form-required-checkboxes element requires at least one attribute to function, but using some of the others you can more fully customize the experience for users:

• required - Represents the range of required values. You can set this up in one of three ways depending on your needs:
  • Single number (e.g., 3) requires exactly that number of choices.
  • Range (e.g., 3-5) requires a minimum of the first number and a max of the second number be chosen.
  • Max (e.g., 0-3) requires a minimum of zero and a max of the second number to be chosen.
• notice (optional) - This is a string description that explains details of the required value in plain language. If you don’t supply one, the component will create one for you based on the current language (if supported). This description will be added as a small element within the component (as a sibling to the fieldset).
• error (optional) - This is a string validation error you’d like to be shown when the validation criteria is not met. If not provided, an appropriate error message will be generated based on the current language (if supported).
• lang (optional) - Language code for localized messages (e.g., “en,” “es,” “fr,” “de”). Falls back to the nearest ancestor’s lang attribute or the document language.

# Localization

The component now includes built-in translations for 16 languages: English, Chinese (Mandarin), Hindi, Spanish, French, Arabic, Bengali, Portuguese, Russian, Japanese, German, Punjabi, Javanese, Korean, Vietnamese, and Italian. Messages are automatically generated based on the lang attribute.

You can use it like this:

<form-required-checkboxesrequired=“3”lang=“es”><fieldset><legend>Opciones</legend><!-- Will display: “Elija 3 de la lista” --></fieldset></form-required-checkboxes>

The component automatically detects the language from the lang attribute on the element itself, the nearest ancestor element, or the document’s lang attribute, falling back to English if none is found.

You can also register custom translations or override existing ones using the FormRequiredCheckboxesElement.registerTranslations() static method. Regional language codes (e.g., en-US, es-MX) automatically fall back to their base language.

# Demo

I put together a comprehensive demo of the web component over on GitHub:

# Grab It

You can view the entire project (and suggest enhancements) over on the component’s Github repo.

Step 2: Add in some HTML web components!