Use Builder web components to display dynamic Builder content on any tech stack.
With the script tag and the <builder-component> custom element, you can optionally set the targeting attributes for Builder to load content dynamically. For example:
<builder-component model="page" api-key="YOUR_API_KEY">
<!-- HTML here displays while your content is loading,
for example, put a gif here, or leave empty -->
</builder-component>
<script async src="https://cdn.builder.io/js/webcomponents"></script>
Required: Yes
Description: The name of the your page or component model to display
Required: Yes
Description: Your Builder Public API Key
Required: No
Load a specific Builder entry by ID, e.g.
<builder-component entry="3dasdf3" model="page" api-key="YOUR_KEY">
</builder-component>Required: No
If on, the component observes location pushState events and reloads when the browser URL changes client side; for example, if you target different content for this code at different URL paths.
<builder-component reload-on-route model="page" api-key="YOUR_KEY">
</builder-component>Required: No
Full Builder options object as JSON to customize how content is requested.
<builder-component options='{"cacheSeconds": 10}' model="page" api-key="YOUR_KEY">
</builder-component>Fires when the Builder content loads and passes you the data loaded. Good for transitioning content or tracking analytics such as which Builder content and A/B tests were viewed to other analytics providers.
element.addEventListener('load', event => {
var data = event.detail?.data
if (!data) {
// No matching content was found
show404()
} else {
animateIn()
}
})Fires when builder content fails to load.
element.addEventListener('error', event => {
console.error(event.detail)
showErrorPage()
})If you need to run some logic before Builder web components fetch and render, you can declare a window variable called builderWcLoadCallbacks as in the example below:
<script>
window.builderWcLoadCallbacks = [
(context) =>
context.builder.setUserAttributes({
/* Add your targeting attributes for Builder
* to dynamically load content to the web component above
*/
locale: navigator.language,
}),
];
</script>This code snippet sets up a builderWcLoadCallbacks callback function that runs when the Builder web component loads. Inside the callback, the context.builder.setUserAttributes() method is used to set targeting attributes for the Builder component, allowing dynamic loading of content based on these attributes.
This example features:
window.builderWcLoadCallbacks: This is an array that holds callback functions to be executed when the Builder web component loads.(context) => ...: This is an arrow function that takes a parametercontext, which represents the context of the Builder component. Thecontextparameter provides access to various methods and data related to the Builder component.context.builder.setUserAttributes({ ... }): This method is called on thecontext.builderobject to set user targeting attributes. Targeting attributes are used to customize the content displayed by the Builder component based on specific conditions.{ locale: navigator.language }: This is an example of a targeting attribute being set. In this case, it sets thelocaleattribute to the value ofnavigator.language, which represents the user's preferred language as detected by the browser.
By setting these attributes, you can dynamically load content into the web component based on specific criteria, such as the user's language in this example. In this way, you can provide personalized content based on the user's context and preferences.
Register custom elements with Builder to get support for custom blocks in Builder for any framework.
For example, suppose you have a web component called my-hero that takes a title and subtitle as in the following example:
<my-hero title="Hello world" subtitle="Lorem ipsum"></my-hero>And the MyHero class has the following definition:
class MyHero extends HTMLElement { /* ... */ }
customElements.define('my-hero', MyHero)You can register it in your code, as in the following example:
<script>
// When the SDK loads
window.builderWcLoadCallbacks = [
(context) => {
// Register each component
context.Builder.registerComponent(null, {
name: 'My Hero',
tag: 'my-hero',
inputs: [
{ name: 'title', type: 'string', defaultValue: 'Hello world' },
{ name: 'subTitle', type: 'string', defaultValue: 'Lorem ipsum' }
]
})
}
];
</script>
For more on Builder's supported import types, read Input Types. Note that for web components Builder only supports primitive elements–such as text, number, boolean–but not deep objects and arrays like lists and maps.
You can also wrap components in your favorite framework as custom elements; for examples, see Using React in your Web Components in the React documentation and Vue's web component wrapper on GitHub.
In the Builder component, <builder-component>, you can pass data and functions to your UI. This way you can bind data values to UI elements, such as text values or lists, and define actions triggered by events such as clicking a button.
Any data passed down to <builder-component> is accessible within Builder actions and bindings using the state.* syntax. For instance, if you pass down products as data, you can access it within the component using state.products.
Support for passing data was introduced in the pre-production release version 1.3.47. To use this functionality, be sure to specify this version explicitly.
The following code snippet demonstrates these guidelines and dynamically sets the text of a button using the Builder component with the example "buttonText" as "Click Me."
<builder-component
prerender="false"
id="builder-component-element"
model="page"
api-key="your-api-key"
></builder-component>
<script>
window.builderWcLoadCallbacks = [async function () {
const element = document.getElementById("builder-component-element");
await customElements.whenDefined("builder-component");
element.setState({
buttonText: "Click Me"
});
// You can pass functions, custom objects, and libraries down
// to the Builder component using context, which is similar to
// React context. Context data is propagated down the component
// hierarchy, allowing components to access it.
// However, the context data is not observed for changes or
// mutations, meaning that changes to the context data
// won't automatically trigger component updates.
element.setContext({
service: new Service({ message: 'hello world' })
});
}]
</script>
<!-- load the script with version explicitly set to 1.3.47 -->
<script
async
src="https://cdn.builder.io/js/webcomponents@1.3.47"
></script>
The code example:
- Sets up
<builder-component>. - Passes data using
setState(). - Demonstrates how to pass functions and complex data through the
setContext()method. - Explicitly specifies version 1.3.47 in the
scriptto load the specified version of the Builder component from the CDN.
