Watch Webinar: Figma - Design to Code in 80% Less Time

Announcing Visual Copilot - Figma to production in half the time

Builder.io logo
Talk to Us
Contact Sales
Platform
Developers
Talk to Us

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

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

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 script to load the specified version of the Builder component from the CDN.
Was this article helpful?

Product

Visual CMS

Theme Studio for Shopify

Sign up

Login

Featured Integrations

React

Angular

Next.js

Gatsby

Get In Touch

Chat With Us

Twitter

Linkedin

Careers

© 2020 Builder.io, Inc.

Security

Privacy Policy

Terms of Service

Newsletter

Get the latest from Builder.io

By submitting, you agree to our Privacy Policy