Best Practices

• Promote / Enable Semantic HTML [Russell]
  • Custom Elements should increase the readability of HTML source code, and simplify its construction
• Custom Elements should be Accessible
• Events from encapsulated elements should not bubble out of the component. [Russell]
  • component may re-emit with the component as target
• Set element display style (block, inline-block, flex) [Google]
  • default for custom element is inline, which usually is not what is intended
• Add an element display style that respects the hidden attribute [Google]
  • A custom element with a default display style, e.g. :host { display: block }, will override the lower specificity built-in hidden attribute. This may surprise you if you expect setting the hidden attribute on your element to render it display: none. In addition to a default display style, add support for hidden with :host([hidden]) { display: none }.
• Do not override author-set, global attributes. [Google]
  • Global attributes are those that are present on all HTML elements. Some examples include tabindex and role. A custom element may wish to set its initial tabindex to 0 so it will be keyboard focusable. But you should always check first to see if the developer using your element has set this to another value. If, for example, they've set tabindex to -1, it's a signal that they don't wish for the element to be interactive.
• Always accept primitive data (strings, numbers, booleans) as either attributes or properties. [Google]
  • Custom elements, like their built-in counterparts, should be configurable. Configuration can be passed in declaratively, via attributes, or imperatively via JavaScript properties. Ideally every attribute should also be linked to a corresponding property.
• Aim to keep primitive data attributes and properties in sync, reflecting from property to attribute, and vice versa. [Google]
  • You never know how a user will interact with your element. They might set a property in JavaScript, and then expect to read that value using an API like getAttribute(). If every attribute has a corresponding property, and both of them reflect, it will make it easier for users to work with your element. In other words, calling setAttribute('foo', value) should also set a corresponding foo property and vice versa. There are, of course, exceptions to this rule. You shouldn't reflect high frequency properties, e.g. currentTime in a video player. Use your best judgment. If it seems like a user will interact with a property or attribute, and it's not burdensome to reflect it, then do so.
• Aim to only accept rich data (objects, arrays) as properties. [Google]
  • Generally speaking, there are no examples of built-in HTML elements that accept rich data (plain JavaScript objects and arrays) through their attributes. Rich data is instead accepted either through method calls or properties. There are a couple obvious downsides to accepting rich data as attributes: it can be expensive to serialize a large object to a string, and any object references will be lost in this stringification process. For example, if you stringify an object which has a reference to another object, or perhaps a DOM node, those references will be lost.
• Do not reflect rich data properties to attributes. [Google]
  • Reflecting rich data properties to attributes is needlessly expensive, requiring serializing and deserializing the same JavaScript objects. Unless you have a use case that can only be solved with this feature, it's probably best to avoid it.
• Consider checking for properties that may have been set before the element upgraded. [Google]
  • A developer using your element may attempt to set a property on the element before its definition has been loaded. This is especially true if the developer is using a framework which handles loading components, stamping them to the page, and binding their properties to a model.
• Express state as Attributes, not Classes. [Google - Do not self apply classes]
  • The class attribute is generally considered to be owned by the developer using your element, and writing to it yourself may inadvertently stomp on developer classes.
• Dispatch events in response to internal component activity.
  • Your component may have properties that change in response to activity that only your component knows about, for example, if a timer or animation completes, or a resource finishes loading. It's helpful to dispatch events in response to these changes to notify the host that the component's state is different.
  • This reduces the need for attribute/property observers
• [REVIEW] Do not dispatch events in response to the host setting a property (downward data flow). [Google]
  • Dispatching an event in response to a host setting a property is superfluous (the host knows the current state because it just set it). Dispatching events in response to a host setting a property may cause infinite loops with data binding systems.
• Do not use attributeChangedCallback to reflect state to an underlying property [Google]
  • This can result in infinite loop scenarios.
  • Instead, implment property as accessors that reflect to the attribute
  • Attribute changed callback can apply SIDE EFFECTS of the attribute change
• Make properties lazy [Google]
  • prevent developers / frameworks from shadowing custom element properties by setting properties before upgrade
  • see https://developers.google.com/web/fundamentals/web-components/best-practices#lazy-properties
• Mimic built-in elements as closely as possible [webcomponents]
  • Your component should feel just like any other natively implemented element to developers.
• Fail Silently [webcomponents]
  • Components should act like native DOM elements, so avoid creating elements that throw JS errors from ordinary DOM interactions, for example: you can place a
    inside a

    , and while it may not behave or render normally, it shouldn't throw errors either.

  Promote/Enable Semantic HTML Custom Elements should be Accessible

  Reference

  Best Practices

  (Google Web Fundamentals)[https://developers.google.com/web/fundamentals/web-components/best-practices] (webcomponents.org)[https://www.webcomponents.org/community/articles/web-components-best-practices] (Mattia Astorino:Web Components - The Right Way)[https://equinsuocha.io/blog/web-components-the-right-way/] (WebComponents Gold Standard)[https://github.com/webcomponents/gold-standard/wiki]

  HowTo

  (Redirecting Dom Events)[https://www.growingwiththeweb.com/2016/07/redirecting-dom-events.html]

  Other

  (Kai Wedekind: 6 Reasons You Should Use Native Web Components)[https://codeburst.io/6-reasons-you-should-use-native-web-components-b45e18e069c2]

  Outdated

  (Mateus Ortiz webcomponents the right way git repo - very out of date!)[https://github.com/mateusortiz/webcomponents-the-right-way]