Skip to content
Skip to main contentWhere does your team stand on AI adoption?
CONTACT SALESSTART BUILDING

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"> <!-- 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>

Subresource Integrity (SRI)

Every time the web components script is published to Builder's CDN, Builder generates an integrity hash for that exact file. You can add this hash to the integrity attribute on your script tag:

<script async src="https://cdn.builder.io/js/webcomponents@2.0.1" integrity="sha384-4kv8UvE8cZpCY5WWDnozOBeWab+HcwN7f6nPCeB5kEAZi3yQWy3GMmPmYSvvxH5N" crossorigin="anonymous"></script>

Pinning to a specific version and setting integrity means the script only runs if the fetched file matches the expected hash exactly, and crossorigin="anonymous" is required for the browser to perform this check.

If you use the unversioned https://cdn.builder.io/js/webcomponents URL, the file can change over time, so omit the integrity attribute. To useintegrity, pin to a fixed version as in the example above.

Attributes

model

Required: Yes

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

api-key

Required: Yes

Description: Your Builder Content Public API Key

entry

Required: No

Load a specific Builder Content 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 Content 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 Content 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 Content web component loads.
  • (context) => ...: This is an arrow function that takes a parameter context, which represents the context of the Builder Content component. The context parameter provides access to various methods and data related to the Builder Content 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 Content 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

Register custom elements with Builder Content to get support for custom blocks in Builder Content 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 Content 's supported import types, read Input Types. Note that for web components Builder Content 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 Content 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 Content 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 Content 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 --> <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 Content component from the CDN.
Was this article helpful?