Bulletproof Web Component APIs

Web components/custom elements provide some great features that can make your UX more efficient and scalable, but there are some "gotchas" that can prevent teams from having a good experience with your components.

The Problem

One of the great things about custom elements/web components can sometimes be a challenge for them - they can be used anywhere. You never know if they're being used in a framework, in a type-safe environment, rendered on the server with a language like PHP, created programmatically using JavaScript's createElement function, or even in plain ol' HTML.

The challenge is that there's no consistent way to ensure your web component APIs are correctly implemented. Because of this, one of the items in our component library's PR checklist is:

✅ Attributes and properties work when set, unset, and poorly set.

For example, in our library, we have an "input" component that, like a native <input> element, has a type attribute with some specified values. It doesn't have all of the same options because we have specific components for some of the other controls like radios and checkboxes.

/** A string specifying the type of control to render. */
@property()
type:
  | 'color'
  | 'date'
  | 'email'
  | 'number'
  | 'password'
  | 'search'
  | 'tel'
  | 'text' = 'text';

NOTE: The code examples are using Lit, but the principles discussed here can be applied to other libraries and frameworks.

When we test testing this attribute, we get inconsistent results.

• Set
  • everything works as expected.

<my-input type="color"></my-input>
<my-input type="date"></my-input>
<my-input type="email"></my-input>
<my-input type="number"></my-input>
<my-input type="password"></my-input>
<my-input type="search"></my-input>
<my-input type="tel"></my-input>
<my-input type="text"></my-input>

• Unset
  • the component works fine when the attribute is not set because of the default value
  • the component renders correctly when the property is undefined because the internal HTML element is resilient, but the custom logic and validation in the component break

// When the attribute is not set
<my-input></my-input>

// When the property is `undefined` (example using JSX)
<my-input type={undefined}></my-input>

• Poorly set
  • setting the type attribute value to "rubbish" renders a text input, but also breaks our custom logic and validation.
  • setting it to a value that is a valid HTML input type, but not one that we have specified for the component, renders controls not intended for our component which not only breaks our custom logic and validation, but also our styles/designs.

<!-- not a real type -->
<my-input type="rubbish"></my-input>

<!-- we don't want users using this type -->
<my-input type="range"></my-input>

You can test this example here:

How do we fix it?

I noticed that the native HTML element seems to pass the "set, unset, and poorly set" test, so let's see if we can learn from it.

When I poorly set the native input's attribute and log the property values, I can see why it works.

<!-- set the value to a non-standard type -->
<input type="rubbish" />
<input id="undefinedInput" />

<script>
  // programmatically set the value to `undefined`
  undefinedInput.type = undefined;

  console.log(rubbishInput.type);   // logs 'text'
  console.log(undefinedInput.type); // logs 'text'
</script>

If an invalid value is assigned to the attribute or property, it falls back to a default value. We should be able to do the same and still maintain strong typing.

Let's start by creating a list of valid values and a type for our property.

const inputTypes = [
  'color',
  'date',
  'email',
  'number',
  'password',
  'search',
  'tel',
  'text',
] as const;

We can use the array to create a union type for TypeScript validation.

type InputType = typeof inputTypes[number];

Now we can update our custom elements property with some validation logic. We can do this by converting our existing property to a standard JavaScript class getter and setter.

// private property for storing the `type` property value
private _type: InputType = 'text';

/** A string specifying the type of control to render. */
@property()
set type(value: InputType) {
  // Confirming the value is in our approved list of values. If not, it will use a fallback value of "text"
  this._type = inputTypes.includes(value) ? value : 'text';
}

get type(): InputType {
  return this._type;
}

Here's our final output:

Conclusion

With this new validation in place, our input component is far more resilient than before and also allows for more complex validation if necessary. This method may also be overkill for some of your attributes, especially those that are for styling. For those scenarios, be sure to check out this article.