Frequently Asked Questions
What are these custom element things?
Custom elements are a new web standard which let developers
create their own HTML Elements. Because they're based on web
standards, these elements should work on any page. This means,
you can write a component, like a datepicker, and share it
To learn more, check out the
custom elements primer
best practices guide.
Are you testing that libraries let you author custom elements?
No. These tests just check that a library/framework supports the
usage of custom elements. Essentially we're trying to
answer the question: "If you're building an app in framework X,
and you'd like to include a few custom elements on the page, are
you going to have a bad time?"
The tests check that the library/framework will let you do
things like display a custom element, bind data to it, pass in
children, and listen for events.
Why is each test counted twice?
Each test is run on a browser with native support for all of the
web components standards (template, shadow DOM, custom elements)
and on a browser with polyfilled support. It's possible that a
test may work in the native setting and not in the polyfilled
one, or vice versa. To account for this, we count both
environments as unique tests.
How are the libraries scored?
Each test has an associated weight, based on how critical it is.
The final tally of pass/fails is combined with these weights to
create a weighted average score.
How are basic and advanced tests different?
Basic tests cover things which are fundamental to a
library/framework's ability to display a custom element. For
example, can it display a custom element that contains shadow
DOM? Can it handle setting attributes on the custom element? Can
it listen for DOM events from the element? Failing any of these
tests is a pretty critical issue.
Advanced tests cover more opinionated framework features. For
example, does the framework provide declarative syntax for
listening to events with different casing styles (kebab-case,
camelCase, etc). These are more like "nice to haves" that may
improve the developer experience.
I thought the whole point of Polymer was to write custom
elements. Why doesn't it get a 100%?
Polymer supports a non-standard feature called declarative event
binding, which lets you use attributes to wire up event
on-foo="handleFoo">. Because DOM events are just
strings, there are no rules governing how they should be
formatted or capitalized—"my-event" is just as reasonable as
"myEvent" or "myevent". Even the web platform has a few examples
of oddly cased events like
Because Polymer's implementation of declarative event bindings
relies on pulling the event name from the
attribute, and the HTML parser will always lowercase
attribute names, it is unable to listen for events with
capital letters in their names.
Since it is entirely possible to write a vanilla custom element
that dispatches an event with a capital letter in its name, and
because there is prior art in the platform that actually uses
this technique for event names with acronyms ("DOM"), we feel it
is imporant to test this.
Libraries like Preact also fail these capitalization tests,
which points to a possible best practice of always making event
names lowercase. This is the style most DOM events already use:
mousedown, popstate, beforeunload, etc.
If a library is missing a feature, like declarative event or
property bindings, does it automatically fail those tests?
Not necessarily. If a library omits a
non-standard feature aimed at developer
ergonomics, e.g. declarative event/property bindings, we would
just omit those tests from the scoring process.
Why don't you have tests for _____ library?
We'd like to have as much test coverage as possible, but it's
a fair bit of work building each test suite (especially because
we are not experts in every library). If a framework or library
is not represented it's just because we haven't had a chance to
write tests for it yet.
I want to write some tests for _____ library. Do you accept pull
Yes! In fact, >50% of the tests on this site are from external
If you'd like to contribute, please first
open an issue
saying you'd like to write some tests for a specific
library/framework. This helps ensure that there's not more than
one person writing tests for the same library.