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 any native form control.

# Need customized buttons? You bet!

If you don’t like the default text or your site is in another language — no biggie! 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 the children will become groups managed by the component and their existing values are preserved. Perfect progressive enhancement!

# Need to do something a little 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 this gets picked up by the component, the whole fieldset will become the template. When users add new Guests, all of the numeric values — whether in text or attributes — increment automatically when new groups are added. So in this case, the legend will update, as will the for attribute on the label and id and name attributes on the input.

# Need to constrain the responses? You got it.

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 keep a watchful eye? 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 see the initial field group(s) and can fill them in. They can’t add more, but nothing breaks. Make sure your minimum count accommodates users without JavaScript.

# 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 instance manages all your repeatable field groups with native form participation — no framework required.

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

# What’s included

The template provides everything you need to create 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. Users of your component can choose what works best:

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 to ensure it only runs in browser environments and checks if customElements is available, making 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 found myself copying and adapting the same project structure each time. This template captures those patterns so I — and now you — can start building components faster.

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!

# Where it all started

I had the original idea for “projections” way back in 2019. Inspired by OS X’s Dashboard Widgets and Adobe AIR, I’d begun to wonder if it might be possible to project a component from a website into those kinds of surfaces. Rather than building a bespoke widget that connected to an API, I thought it made sense to leverage an installed PWA to manage those “projections.” I shared the idea at TPAC that year and got some interest from a broad range of folks, but didn’t have much time to work on the details until a few years later.

In the intervening time, I kept working through the concept in my head. I mean in an ideal world, the widget would just be a responsive web page, right? But if that were the case, what happens when every widget loads the entirety of React to render their stock ticker? That seemed like a performance nightmare.

In my gut, I felt like the right way to build things would be to have a standard library of widget templates and to enable devs to flow data into them via a Service Worker. Alex Russell suggested I model the APIs on how Notifications are handled (since they serve a similar function) and I was off to the races.

I drafted a substantial proposal for my vision of how PWA widgets should work. Key aspects included:

• A declarative way to define and configure a widget from within the Web App Manifest;
• A progressively enhanced pathway for devs to design a widget that adapts to its host environment, from using predefined templates to using custom templates to full-blown web-based widgets (with rendering akin to an iframe);
• A collection of recommended stock templates that implementors should offer to support most widget types;
• Extensibility to support custom templates using any of a variety of templating languages; and
• A complete suite of tools for managing widgets and any associated business logic within a Service Worker.

# Widgets became a reality

After continuing to gently push on this idea with colleagues across Microsoft (and beyond), I discovered that the Windows 11 team was looking to open up the new Widget Dashboard to third-party applications. I saw this as an opportunity to turn my idea into a reality. After working my way into the conversation, I made a solid case for why PWAs needed to be a part of that story and… it worked! (It no doubt helped that companies including Meta, Twitter, and Hulu were all invested in PWA as a means of delivering apps for Windows.)

While the timeline for implementation didn’t allow us to tackle the entirety of my proposal, we did carve out the pieces that made for a compelling MVP. This allowed us to show what’s possible, see how folks use it, and plan for future investment in the space.

Sadly, it meant tabling two features I really loved:

• Stock/predefined templates. A library of lightly theme-able, consistent, cross-platform templates based on common data structures (e.g., RSS/Atom, iCal) would make it incredibly simple for devs to build a widget. If implemented well, devs might not even need to write a single line of business logic in their Service Worker as the browser could pick up all of the configuration details from the Manifest.
• Configurable widget instances. Instead of singleton widgets, these would allow you to define a single widget type and replicate it for different use cases. For example, a widget to follow a social media user’s profile could be defined once and the individual instances could be configured with the specific account to be followed.

I’m sincerely hopeful these two features eventually make their way to us as I think they truly unlock the power of the widget platform. Perhaps, with enough uptake on the current implementation, we can revisit these in the not-too-distant future.

To test things out, I decided to build two widgets for this site:

1. Latest posts
2. Latest links

Both are largely the same in terms of their setup: They display a list of linked titles from this site.

# Designing my widget templates

Given that they were going to be largely identical, I made a single “feed” template for use in both widgets. The templating tech I used is called Adaptive Cards, which is what Windows 11 uses for rendering.

Adaptive Card templates are relatively straightforward JSON:

{“type”:“AdaptiveCard”,“$schema”:“http://adaptivecards.io/schemas/adaptive-card.json”,“version”:“1.6”,“body”: [{“$data”:“${take(items,5)}”,“type”:“Container”,“items”: [{“type”:“TextBlock”,“text”:“[${title}](${url})”,“wrap”:true,“weight”:“Bolder”,“spacing”:“Padding”,“height”:“stretch”}],“height”:“stretch”}],“backgroundImage”: {“url”:“https://www.aaron-gustafson.com/i/background-logo.png”,“verticalAlignment”:“Bottom”,“horizontalAlignment”:“Center”}}

What this structure does is:

1. Create a container into which I will place the content;
2. Extract the first five items from the data being fed into the template (more on that in a moment);
3. Loop through each item and
   • create a text block,
   • populate its content with Markdown to generate a linked title (using the title and url keys from the item object)
   • Set some basic styles to make the text bold, separate the titles a little and make them grow to fill the container; then, finally
4. Set a background on the widget.

The way Adaptive Cards work is that they flow JSON data into a template and render that. The variable names in the template map directly to the incoming data structure, so are totally up to you to define. As these particular widgets are feed-driven and this site already supports JSONFeed, I set up the widgets to flow the appropriate feed into each and used the keys that were already there. For reference, here’s a sample JSONFeed item:

{“id”:“…”,“title”:“…”,“summary”:“…”,“content_html”:“…”,“url”:“…”,“tags”:[],“date_published”:“…”}

If you want to tinker with Adaptive Cards and make your own, you can do so with their Designer tool.

# Defining the widgets in the Manifest

With a basic template created, the next step was to set up the two widgets in my Manifest. As they both function largely the same, I’ll just focus on the definition for one of them.

First off, defining widgets in the Manifest is done via the widgets member, which is an array (much like icons and shortcuts). Each widget is represented as an object in that array. Here is the definition for the “latest posts” widget:

{“name”:“Latest Posts”,“short_name”:“Posts”,“tag”:“feed-posts”,“description”:“The latest posts from Aaron Gustafson’s blog”,“template”:“feed”,“ms_ac_template”:“/w/feed.ac.json”,“data”:“/feeds/latest-posts.json”,“type”:“application/json”,“auth”:false,“update”:21600,“icons”:[{“src”:“/i/icons/webicon-rss.png”,“type”:“image/png”,“sizes”:“120x120”}],“screenshots”:[{“src”:“/i/screenshots/widget-posts.png”,“sizes”:“387x387”,“label”:“The latest posts widget”}]}

Breaking this down:

1. name and short_name act much like these keys in the root of the Manifest as well as in shortcuts: The name value is used as the name for the widget unless there’s not enough room, in which case short_name is used.
2. You can think of tag as analogous to class in HTML sense. It’s a way of labeling a widget so you can easily reference it later. Each widget instance will have a unique id created by the widget service, but that instance (or all instances, if the widget supports multiple instances) can be accessed via the tag. But more on that later.
3. The description key is used for marketing the widget within a host OS or digital storefront. It should accurately (and briefly) describe what the widget does.
4. The template key is not currently used in the Windows 11 implementation but refers to the expected standard library widget template provided by the system. As a template library is not currently available, the ms_ac_template value is used to provide a URL to get the custom Adaptive Card (hence “ac”) template. The “ms_” prefix is there because it’s expected that this would be a Microsoft-proprietary property. It follows the guidance for extending the Manifest.
5. The data and type keys define the path to the data that should be fed into the template for rendering by the widget host and the MIME of the data format it’s in. The Windows 11 implementation currently only accepts JSON data, but the design of widgets is set up to allow for this to eventually extend to other standardized formats like RSS, iCal, vCard, and such.
6. update is an optional configuration member allowing you to set how often you’d like the widget to update, in seconds. Developers currently need to add the logic for implementing this into their Service Worker, but this setup allows the configuration to remain independent of the JavaScript code, making it easier to maintain.
7. Finally, icons and screenshots allow us to define how the widget shows up in the widget host and how it is promoted for install.

When someone installs my site as a PWA, the information about the available widgets gets ingested by the browser. The browser then determines, based on the provided values and its knowledge of the available widget service(s) on the device, which widgets should be offered. On Windows 11, this information is routed into the AppXManifest that governs how apps are represented in Windows. The Windows 11 widget service can then read in the details about the available widgets and offer them for users to install.

# Adding widget support to my Service Worker

As I mentioned earlier, all of the plumbing for widgets is done within a Service Worker and is modeled on the Notifications API. I’m not going to exhaustively detail how it all works, but I’ll give you enough detail to get you started.

First off, widgets are exposed via the self.widgets interface. Most importantly, this interface lets you access and update any instances of a widget connected to your PWA.

# Installing a widget

When a user chooses to install a widget, that emits a “widgetinstall” event in your Service Worker. You use that to kickoff the widget lifecycle by gathering the template and data needed to instantiate the widget:

self.addEventListener(“widgetinstall”,(event)=>{console.log(</span><span class="token string">Installing </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>event<span class="token punctuation">.</span>widget<span class="token punctuation">.</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">);event.waitUntil(initializeWidget(event.widget));});

The event argument comes in with details of the specific widget being instantiated (as event.widget). In the code above, you can see I’ve logged the widget’s tag value to the console. I pass the widget information over to my initializeWidget() function and it updates the widget with the latest data and, if necessary, sets up a Periodic Background Sync:

asyncfunctioninitializeWidget(widget){awaitupdateWidget(widget);awaitregisterPeriodicSync(widget);return;}

The code for my updateWidget() function is as follows:

asyncfunctionupdateWidget(widget){const template =await(awaitfetch(widget.definition.msAcTemplate)).text();const data =await(awaitfetch(widget.definition.data)).text();try{await self.widgets.updateByTag(widget.definition.tag,{ template, data });}catch(e){console.log(</span><span class="token string">Couldn’t update the widget </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">, e);}return;}

This function does the following:

1. Get the template for this widget
2. Get the data to flow into the template
3. Use the self.widgets.updateByTag() method to push the template and data to the widget service to update any widget instances connected to the widget’s tag.

As I mentioned, I also have code in place to take advantage of Periodic Background Sync if/when it’s available and the browser allows my site to do it:

asyncfunctionregisterPeriodicSync(widget){let tag = widget.definition.tag;if(“update”in widget.definition){registration.periodicSync.getTags().then((tags)=>{// only one registration per tagif(!tags.includes(tag)){periodicSync.register(tag,{minInterval: widget.definition.update,});}});}return;}

This function also receives the widget details and:

1. Looks to see if the widget definition (from the Manifest) includes an update member. If it has one, it…
2. Checks to see if there’s already a Periodic Background Sync that is registered for this tag. If none exists, it…
3. Registers a new Periodic Background Sync using the tag value and a minimum interval equal to the update requested.

The update member, as you may recall, is the frequency (in seconds) you’d ideally like the widget to be updated. In reality, you’re at the mercy of the browser as to when (or even if) your sync will run, but that’s totally cool as there are other ways to update widgets as well.¹

# Uninstalling a widget

When a user uninstalls a widget, your Service Worker will receive a “widgetuninstall” event. Much like the “widgetinstall” event, the argument contains details about that widget which you can use to clean up after yourself:

self.addEventListener(“widgetuninstall”,(event)=>{console.log(</span><span class="token string">Uninstalling </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>event<span class="token punctuation">.</span>widget<span class="token punctuation">.</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">);event.waitUntil(uninstallWidget(event.widget));});

Your application may have different cleanup needs, but this is a great time to clean up any unneeded Periodic Sync registrations. Just be sure to check the length of the widget’s instances array (widget.instances) to make sure you’re dealing with the last instance of a given widget before you unregister the sync:

asyncfunctionuninstallWidget(widget){if(widget.instances.length ===1&&“update”in widget.definition){await self.registration.periodicSync.unregister(widget.definition.tag);}return;}

# Refreshing your widgets

Widget platforms may periodically freeze your widget(s) to save resources. For example, they may do this when widgets are not visible. To keep your widgets up to date, they will periodically issue a “widgetresume” event. If you’ve modeled your approach on the one I’ve outlined above, you can route this event right through to your updateWidget() function:

self.addEventListener(“widgetresume”,(event)=>{console.log(</span><span class="token string">Resuming </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>event<span class="token punctuation">.</span>widget<span class="token punctuation">.</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">);event.waitUntil(updateWidget(event.widget));});

# Actions

While I don’t want to get too into the weeds here, I do want to mention that widgets can have predefined user actions as well. These actions result in “widget click” events being sent back to the Service Worker so you can respond to them:

self.addEventListener(“widgetclick”,(event)=>{const widget = event.widget;const action = event.action;switch(action){// Custom Actionscase“refresh”:event.waitUntil(updateWidget(widget));break;}});

For a great example of how a widget can integrate actions, you should check out the demo PWAmp project. Their Service Worker widget code is worth a read.

# Result!

With all of these pieces in place, I was excited to see my site showing up in the Widget Dashboard in Windows 11.

You can view the full source code on GitHub:

• “Feed” Adaptive Card Template
• Widget definitions in the Manifest
• Widgets code in my Service Worker

I’m quite hopeful this will be the first of many places PWA-driven widgets will appear. If you’s like to see them supported elsewhere, be sure to tell your browser and OS vendor(s) of choice. The more they hear from their user base that this feature is needed, the more likely we are to see it get implemented in more places.

# Addendum: Gotchas

In wiring this all up, I ran into a few current bugs I wanted to flag so you can avoid them:

• The icons member won’t accept SVG images. This should eventually be fixed, but it was keeping my widgets from appearing as installable.
• The screenshots members can’t be incredibly large. I’m told you should provide square screenshots no larger than 500px ×500px.

Your app should work in a read-only mode without JavaScript.