DEV Community

Cover image for Bulletproof Web Component APIs
Burton Smith
Burton Smith

Posted on • Edited on

4

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';
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode
  • 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>
Enter fullscreen mode Exit fullscreen mode
  • 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>
Enter fullscreen mode Exit fullscreen mode

You can test this example here:

Open in StackBlitz

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>
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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

type InputType = typeof inputTypes[number];
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

Here's our final output:

Open in StackBlitz

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.

Image of AssemblyAI tool

Transforming Interviews into Publishable Stories with AssemblyAI

Insightview is a modern web application that streamlines the interview workflow for journalists. By leveraging AssemblyAI's LeMUR and Universal-2 technology, it transforms raw interview recordings into structured, actionable content, dramatically reducing the time from recording to publication.

Key Features:
🎥 Audio/video file upload with real-time preview
🗣️ Advanced transcription with speaker identification
⭐ Automatic highlight extraction of key moments
✍️ AI-powered article draft generation
📤 Export interview's subtitles in VTT format

Read full post

Top comments (0)

AWS Security LIVE!

Tune in for AWS Security LIVE!

Join AWS Security LIVE! for expert insights and actionable tips to protect your organization and keep security teams prepared.

Learn More

👋 Kindness is contagious

Discover a treasure trove of wisdom within this insightful piece, highly respected in the nurturing DEV Community enviroment. Developers, whether novice or expert, are encouraged to participate and add to our shared knowledge basin.

A simple "thank you" can illuminate someone's day. Express your appreciation in the comments section!

On DEV, sharing ideas smoothens our journey and strengthens our community ties. Learn something useful? Offering a quick thanks to the author is deeply appreciated.

Okay