How-to
Custom elements
Publish components as custom elements
To use your components from another framework or a plain page, build them as custom elements. These two components, a price tag and a star rating, are what this project publishes; the page places them so you can see them in the project itself:
Needs: build.elements in webfluent.app.json, shown below. It claims /: paste it into a new project, or replace the starter's src/pages/Home.wf with it.
component PriceTag(label: String, amount: Number, sale: Bool = false) {
Row(gap: .sm, align: .center) {
Text(label).bold
Text("${amount}")
if sale { Badge("Sale").success }
}
}
component Stars(value: Number = 0) {
event rate(stars: Number)
Row(gap: .xs) {
for n in 1..=5 by n {
Button("{n}", outlined: n > value) {
on click { emit rate(n) }
}
}
}
}
page Preview(path: "/", title: "Preview", description: "The components this project publishes.") {
state stars = 3
Heading("Preview").h1
PriceTag(label: "Pro", amount: 29).sale
Stars(value: stars) { on rate(n) { stars = n } }
}
Name the components in build.elements, in webfluent.app.json:
{ "build": { "output_type": "elements", "elements": ["PriceTag", "Stars"] } }
This HTML places the published components on any page, and listens for a rating:
<script src="/elements.js" defer></script>
<link rel="stylesheet" href="/styles.css">
<price-tag label="Pro" amount="29" sale></price-tag>
<wf-stars value="3"></wf-stars>
<script>
document.addEventListener("rate", (e) => console.log("rated", e.detail));
</script>
How it works
Each name becomes a standard custom element. PriceTag is <price-tag>. A one-word component gets a prefix, so its tag has the hyphen a custom element needs: Stars is <wf-stars>. The build writes elements.js, styles.css, and a page that lists the tags it published.
A published element behaves this way:
- An attribute is a prop. It is read when the element is connected, and again whenever it changes. A
Numberprop is read as a number, and a record, a dictionary or a list as JSON. A prop with a capital in its name is written with a hyphen:publishableKeyis the attributepublishable-key. - A
Boolprop is true when the attribute is present, as HTML readsdisabled, and false when it is="false", so a framework that writes the string still works. - An event the component declares is dispatched as a
CustomEventthat bubbles. Itsdetailis the value the event sends, or a list of them when it sends several. - What the component created goes when the element leaves the document.
React, Vue, Svelte, Angular, Rails, WordPress and a plain page can all place a tag. That is why WebFluent publishes custom elements rather than an adapter per framework: the interface every framework shares is the web platform itself.
Troubleshooting
| What you see | What to do |
|---|---|
|
The build says |
Name the components in |
| The build names a component the project does not declare |
Check the spelling in |
| The tag renders as nothing |
Load |