Don't Rely on Default Attribute Values For Styling Web Components

Don't get me wrong, I have nothing against default values for web component APIs. The problem I have with them is that they are unreliable.

The Problem

A common approach for providing a list of available options for an API is using TypeScript's untion type.

/** The display variant for the button */
@property({reflect: true})
variant: 'default' | 'solid' | 'ghost' = 'default';

Here is some basic CSS to make the variations work.

:host {
  --accent-color: #0265dc;
}

button {
  cursor: pointer;
  padding: 0.5rem;
}

:host([variant='default']) button {
  border: solid 1px var(--accent-color);
  background-color: white;
  color: var(--accent-color);
}

:host([variant='solid']) button {
  border: solid 1px var(--accent-color);
  background-color: var(--accent-color);
  color: white;
}

:host([variant='ghost']) button {
  border: solid 1px transparent;
  background-color: transparent;
  color: var(--accent-color);
}

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

The challenge is custom elements/web components can be used anywhere. They can be inserted in the DOM in strings, in server-side languages like PHP, they can be created in JavaScript's createElement function, or even in standard HTML. What I'm getting at is that there is not always a "type-safe" way to ensure custom element attributes are being set accurately. 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.

Testing Our API

Given these guidelines, let's test the API setup above.

• Set - everything looks good.

<my-button variant="default">Default Button</my-button>
<my-button variant="solid">Solid Button</my-button>
<my-button variant="ghost">My Button</my-button>

• Unset
  • without an attribute set it works fine because we have a default value and it is configured to reflect the attribute on the element when it is set.
  • if we set the variant property to undefined, it breaks the styles.

<!-- No attribute set -->
<my-button>No Attribute Button</my-button>

<!-- JSX example -->
<my-button variant={undefined}>Unset Button</my-button>

• Poorly set - when we set the variant attribute to "rubbish" it also breaks.

<my-button variant="rubbish">Rubbish Button</my-button>

You can test this example here:

Fixing the API

The easiest way to fix this is to make the button element styles match the default styles.

button {
  border: solid 1px var(--accent-color);
  background-color: white;
  color: var(--accent-color);
  cursor: pointer;
  padding: 0.5rem;
}

Now we can remove the code for the default variation.

/* We can remove this */
:host([variant='default']) button {
  border: solid 1px var(--accent-color);
  background-color: white;
  color: var(--accent-color);
}

To avoid confusion, you can leave the style and add a comment.

/* Styles for this variant are under the `button` element */
:host([variant='default']) { }

Let's also update the TypeScript API to make it optional and remove the default value.

/** The display variant for the button */
@property({ reflect: true })
variant?: 'default' | 'solid' | 'ghost';

The elements now behave consistently if the value is set, unset, or poorly set!

You can see the final code here:

Conclusion

By removing a dependency on default values, you can create more resilient web component APIs. If you must have default values for your components to function properly, be sure to check out this article to create web components that work consistently.