Facet is a single-file web library that allows for the easy, declarative definition of web components. By making use of <template>
elements with special attributes, Facet makes it possible to define useful and effective web components with no Javascript boilerplate, so you can focus entirely on the structure and behavior of your component.
Like what you see? Consider buying me a coffee π
You can download facet.min.js
from this repository and reference it locally, or retrieve it directly from a CDN like JSDelivr. Facet will automatically detect component definitions in your page's HTML and convert them into web components.
<script src="https://cdn.jsdelivr.net/gh/kgscialdone/[email protected]/facet.min.js"></script>
Facet components are defined with <template component>
elements, which will be automatically detected when the page loads. Facet uses the browser's custom elements API internally, so Facet components are treated just like normal HTML elements.
<template component="hello-world">
<p>Hello, <slot>world</slot>!</p>
</template>
<hello-world></hello-world>
<hello-world>Facet</hello-world> <!-- replaces "world" with "Facet" -->
By default, Facet components use the shadow DOM in closed
mode. You can adjust this with the shadow
attribute, which accepts open
, closed
, or none
.
<template component="hello-world" shadow="none">
<p>Hello, world!</p>
</template>
You can also define a list of attributes to be observed by the component; any attributes defined here will trigger the component's attributeChanged
event when changed, allowing your code to respond to the update. (See Attaching Behavior for details on <script on>
.)
<template component="observed-attrs" observe="name title">
<script on="attributeChanged">console.log(event.detail.name)</script>
</template>
In many cases, it's beneficial to be able to define attributes where a component is used, and have those attributes change the behavior of elements inside the component. Facet achieves this through inherited attributes, which make copying attributes deeper into your components quick and easy.
<template component="labeled-input">
<label inherit="name>for required"><slot>Input</slot></label>
<input inherit="name>id type value required placeholder">
</template>
<labeled-input name="email" type="email" required>Email</labeled-input>
When inheriting attributes, you can use them as-is, rename them, filter them through a Javascript function, or both:
<p inherit="title">Lorem ipsum dolor sit amet...</p>
<p inherit="label>title">Lorem ipsum dolor sit amet...</p>
<p inherit="title/uppercase">Lorem ipsum dolor sit amet...</p>
<p inherit="label>title/uppercase">Lorem ipsum dolor sit amet...</p>
<script>
function uppercase(string) { return string.toUpperCase() }
</script>
<!-- Or define your filter functions inside your component like this! -->
<!-- They'll be scoped to just that component and won't conflict with anything else. -->
<script filter="uppercase">
return value.toUpperCase()
</script>
In addition, attributes that are both observed and inherited will automatically update whenever the component's attribute is changed:
<template component="observe-inherit" observe="div-style">
<div inherit="div-style>style"></div>
</template>
<!-- Changing the div-style attribute will automatically update the inner <div>'s styles! -->
<observe-inherit div-style="width:100%;height:100%;background:rebeccapurple;"></observe-inherit>
Since Facet components are defined entirely in HTML, you don't have the opportunity to edit the component class directly to add your behavior. Instead, Facet searches for <script on>
elements inside of component definitions, and attaches their contents to their parent elements as event handlers.
<template component="immediate-alert">
<script on="connect">alert("You've been alerted immediately!")</script>
</template>
Event handler scripts don't have to be at the top level of the component; they'll be attached to whatever their parent element is, allowing you to easily define complex behaviors for any part of your component.
<template component="click-alert">
<button> <!-- Click handler will be attached here!-->
Alert me!
<script on="click">alert("I've been clicked!")</script>
</button>
</template>
Facet exposes components' lifecycle hooks as custom events, which works hand in hand with event handler scripts to allow flexible, easy definition of custom behavior.
Component Class Function | Facet Event | event.detail |
---|---|---|
connectedCallback |
connect |
{ component } |
disconnectedCallback |
disconnect |
{ component } |
adoptedCallback |
adopt |
{ component } |
attributeChangedCallback |
attributeChanged |
{ component, name, newValue, oldValue } |
In addition, event handler scripts have access to a small handful of magic variables, in a similar way to the onclick
event handler attribute family.
Magic Variable | Description |
---|---|
this |
The element to which the handler script is attached (parent element). |
host |
The host component. |
root |
The host component's shadow root (or the host component if shadow="none" ). |
event |
The event that triggered the handler. |
You can also adjust how event handler scripts act with the once
, capture
, and passive
attributes, which correspond to their respective equivalents in addEventListener
's options
parameter. If the attribute is present, the corresponding option will be set to true
, otherwise it will follow the browser defaults.
Facet also provides a mixin system in order to facilitate code reuse between similar components. Like components, mixins are defined with <template>
elements, and their contents are appended to the shadow DOM of any component they're mixed into.
<template mixin="alert">
<script on="connect">alert("Connected!")</script>
</template>
<template component="hello-world" mixins="alert">
<p>Hello, <slot>world</slot>!</p>
</template>
<template component="goodbye-world" mixins="alert">
<p>Goodbye, <slot>world</slot>...</p>
</template>
<hello-world></hello-world> <!-- alerts on connect -->
<goodbye-world></goodbye-world> <!-- alerts on connect -->
Mixins with the global
attribute will be automatically applied to all components on a page.
<!-- Now every component will alert on connect! -->
<template mixin="alert" global>
<script on="connect">alert("Connected!")</script>
</template>
Mixins with the prepend
attribute will prepend their contents instead of appending them.
<template mixin="lorem" prepend>Lorem ipsum dolor sit amet...</template>
<template component="prepended-mixins" mixin="lorem">
is a pretty weird choice of filler text, if you think about it.
</template>
You can define customized built-in elements with the extends
attribute.
<template component="lorem-ipsum" extends="p">
Lorem ipsum dolor sit amet... <slot></slot>
</template>
<p is="lorem-ipsum">is a pretty weird choice of filler text, if you think about it.</p>
You can define form-associated custom elements with the forminput
attribute.
<template component="inc-dec" forminput>
<script on="connect" once>host.innerText = host.value</script>
<button>+ <script on="click">host.innerText = ++host.value</script></button>
<span><slot></slot></span>
<button>- <script on="click">host.innerText = --host.value</script></button>
</template>
<inc-dec value="0"></inc-dec>
While Facet's defaults are designed to serve the majority of use cases out of the box, it does have a small handful of configuration options, which can be adjusted via attributes on the <script>
tag that imports the Facet library.
Requires a prefix on the component
and mixin
attributes to help avoid conflicts. The prefix defaults to facet-
if no value is supplied to the attribute.
<!-- With default prefix -->
<script src="facet.min.js" namespace></script>
<template facet-component="hello-world">
<p>Hello, <slot>world</slot>!</p>
<script on="connect">console.log(this)</script>
</template>
<!-- With custom prefix -->
<script src="facet.min.js" namespace="fc-"></script>
<template fc-component="hello-world">
<p>Hello, <slot>world</slot>!</p>
<script on="connect">console.log(this)</script>
</template>
Prevents the automatic discovery of component and mixin definitions, requiring you to manually call facet.discoverDeclarativeComponents
yourself.
<script src="facet.min.js" libonly></script>
<script defer>facet.discoverDeclarativeComponents(document)</script>
Changes the default shadow root mode for new components. Equivalent to the shadow
attribute on individual components.
<script src="facet.min.js" shadow="none"></script>
While Facet strives to never require you to write Javascript for any of its core behavior, it does expose its internal workings as a basic Javascript API. Facet's API is intentionally not perfectly ergonomic, since the declarative <template>
-based interface described above is always the intended use case, but there are some things that can only be realistically achieved with Javascript, such as single-file importable components.
Function | Description |
---|---|
facet.defineComponent(tagName, template, options) |
Define a new component. |
facet.defineMixin(name, template, options) |
Define a new mixin. |
facet.discoverDeclarativeComponents(root) |
Find and define all components and mixins in a given parent element. |
Variable | Description |
---|---|
facet.config.namespace |
The required namespace prefix for the component and mixin attributes. |
facet.config.autoDiscover |
If false, skip automatic discovery of components/mixins on page load. |
facet.config.defaultShadowMode |
The default shadow root mode for new components. |
facet.mixins |
Information about all currently defined mixins. |
Facet's source code is also lovingly commented with JSDoc, which keeps it lightweight and build-step free while still enabling Typescript users to rest easy about type safety when interacting with Facet's API.
βββββ "Anyone exploring web components really would do themselves a major favor giving this a solid look."
βββββ "Facet is the first time I've looked at WebComponents and thought 'oh, I get this, I get what it's for'."
βββββ "This is exactly what I thought web components should be."
βββββ "Holy f***, this is awesome!"
βββββ "I never thought much of web components but this really changes my view."
* All reviews are real quotes from users, but are used here in jest and with permission.
Thank you so much to these $5/mo+ sponsors for your support!
- Morgan Murrah ($5/mo)