Web Components API

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">  </builder-component> <script async src="https://cdn.builder.io/js/webcomponents"></script>

Attributes

`model`

Required: Yes

Description: The name of the your page or component model to display

`api-key`

Required: Yes

Description: Your Builder Public API Key

`entry`

Required: No

Load a specific Builder entry by ID, e.g.

<builder-component entry="3dasdf3" model="page" api-key="YOUR_KEY"> </builder-component>

`reload-on-route`

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>

`options`

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>

Events

`load`

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() } })

`error`

Fires when builder content fails to load.

element.addEventListener('error', event => { console.error(event.detail) showErrorPage() })

Initializing

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:

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 parameter context, which represents the context of the Builder component. The context parameter provides access to various methods and data related to the Builder component.
context.builder.setUserAttributes({ ... }): This method is called on the context.builder object 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 the locale attribute to the value of navigator.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.

Registering custom elements

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:

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.

Passing data and context for binding

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 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.

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>  <script async src="https://cdn.builder.io/js/webcomponents" ></script>

The code example:

Sets up builder-component.
Passes data using setState().
Demonstrates how to pass functions and complex data through the setContext() method.
Loads the Builder component from the CDN.

Was this article helpful?