Custom Element Best Practices

Custom elements let you construct your own HTML tags. This checklist covers best practices to help you build high quality elements.

Custom elements allow you to extend HTML and define your own tags. They're an incredibly powerful feature, but they're also low-level, which means it's not always clear how best to implement your own element.

To help you create the best possible experiences we've put together this checklist. It breaks down all the things we think it takes to be a well behaved custom element.

Checklist

Shadow DOM

Attributes and properties

Events

Explainers

Don't override the page author

It's possible that a developer using your element might want to override some of its initial state. For example, changing its ARIA role or focusability with tabindex. Check to see if these and any other global attributes have been set, before applying your own values.

connectedCallback() {
  if (!this.hasAttribute('role'))
    this.setAttribute('role', 'checkbox');
  if (!this.hasAttribute('tabindex'))
    this.setAttribute('tabindex', 0);

Make properties lazy

A developer might attempt to set a property on your element before its definition has been loaded. This is especially true if the developer is using a framework which handles loading components, inserting them into to the page, and binding their properties to a model.

In the following example, Angular is declaratively binding its model's isChecked property to the checkbox's checked property. If the definition for howto-checkbox was lazy loaded it's possible that Angular might attempt to set the checked property before the element has upgraded.

<howto-checkbox [checked]="defaults.isChecked"></howto-checkbox>

A custom element should handle this scenario by checking if any properties have already been set on its instance. The <howto-checkbox> demonstrates this pattern using a method called _upgradeProperty().

connectedCallback() {
  ...
  this._upgradeProperty('checked');
}

_upgradeProperty(prop) {
  if (this.hasOwnProperty(prop)) {
    let value = this[prop];
    delete this[prop];
    this[prop] = value;
  }
}

_upgradeProperty() captures the value from the unupgraded instance and deletes the property so it does not shadow the custom element's own property setter. This way, when the element's definition does finally load, it can immediately reflect the correct state.

Avoid reentrancy issues

It's tempting to use the attributeChangedCallback() to reflect state to an underlying property, for example:

// When the [checked] attribute changes, set the checked property to match.
attributeChangedCallback(name, oldValue, newValue) {
  if (name === 'checked')
    this.checked = newValue;
}

But this can create an infinite loop if the property setter also reflects to the attribute.

set checked(value) {
  const isChecked = Boolean(value);
  if (isChecked)
    // OOPS! This will cause an infinite loop because it triggers the
    // attributeChangedCallback() which then sets this property again.
    this.setAttribute('checked', '');
  else
    this.removeAttribute('checked');
}

An alternative is to allow the property setter to reflect to the attribute, and have the getter determine its value based on the attribute.

set checked(value) {
  const isChecked = Boolean(value);
  if (isChecked)
    this.setAttribute('checked', '');
  else
    this.removeAttribute('checked');
}

get checked() {
  return this.hasAttribute('checked');
}

In this example, adding or removing the attribute will also set the property.

Finally, the attributeChangedCallback() can be used to handle side effects like applying ARIA states.

attributeChangedCallback(name, oldValue, newValue) {
  const hasValue = newValue !== null;
  switch (name) {
    case 'checked':
      // Note the attributeChangedCallback is only handling the *side effects*
      // of setting the attribute.
      this.setAttribute('aria-checked', hasValue);
      break;
    ...
  }
}