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

Custom data and context

Custom actions give you a powerful tool for creating dynamic and interactive experiences in Builder. You can add new functionality to your UI, reuse code across multiple components, and create a more engaging and user-friendly experience for your users.

Tip: The techniques covered in this document are for the Gen 1 React SDK. For detailed information on the Gen 2 SDKs, visit SDK Comparison.

What to know

  • The data and context properties allow you to pass information and functionality to your Builder components.
  • The data and context properties are optional for Builder components.

Passing data down with BuilderComponent

To pass data down, use the data prop in the BuilderComponent and assign it an object with key-value pairs. For example, you can pass a list of products and additional data, such as an isLoggedIn boolean:

Framework
Meta-Framework
SDK Generation
<BuilderComponent model="page" content={builderJson} data={{ products: productsList, isLoggedIn: true, }} />

The data passed down is available in Builder actions and bindings using the prefix state.*. For example, state.products refers to the productsList passed down in the example above.

To inspect what fields are currently available in state, add console.log(state) to your Edit Content JS + CSS panel. This is useful when a binding returns undefined unexpectedly.

You can also pass down functions and complex data using the context prop. For example:

Framework
Meta-Framework
SDK Generation
<BuilderComponent model="page" content={builderJson} context={{ lodash: lodash, addToCart: () => myService.addToCart(currentProduct), }} />

Here, the context object is assigned two key-value pairs:

  • a function addToCart()
  • the library lodash

The context passed down is available in Builder using the prefix context.*. For example, context.lodash refers to the lodash library passed down in the example above.

Distinguish between context and data

Both context and data are optional arguments for a BuilderComponent. The key difference is how they are used and what they represent.

Context

Use the context prop to pass globally available objects or functions, such as utilities or services used across multiple components.

The context prop is not directly accessible to visual editor users, making it less visible than the data prop. This makes it ideal for exposing JavaScript libraries, utility functions, or global data within Builder.

Data

Use the data prop to pass content-specific data that affects rendering or behavior in the BuilderComponent.

The data prop is accessible in the visual editor. Users can view this data in the Data tab under the Content State panel. This data could then be utilized within the Element data bindings panel. For instance, the data prop could store user details like a username.

Example: setting up a custom action on a button

You can add an action to any element, though button actions are frequently customized, which this section covers.

In your code: passing down a function

The following example demonstrates a context object that defines a single function called myFunction(), which displays an alert with "Hi!" when called.

Framework
Meta-Framework
SDK Generation
export default () => ( <BuilderComponent model="page" content={builderJson} context={{ myFunction: () => alert('Hi!') }} /> )

By passing down functions using the context prop, you can create flexible and dynamic UI components in the Builder Visual Editor that respond to user input and other events.

In Builder: adding an on click event

To assign the function to run on click of a button:

  1. Select the button.
  2. Go to the Data tab.
  3. Expand the Element events section. For this example, leave the default of On to click.
  4. Click the + New Event button.
  5. Click Edit Action > + Action > Custom Code.
  6. Add your custom Javascript. In this example, add context.myFunction().

The following video demonstrates this process:

After you've set up a custom action on an element, such as a button, you can save the element as a Template or Symbol for reusability.

Data binding in rich text fields

In addition to custom actions and passing data down with BuilderComponent, Builder supports data binding directly within rich text fields. This feature means you can dynamically insert content into any text or link value using state variables.

When using data binding in rich text fields, for example, state.someValue, you must set up your Node server correctly so that this functionality works in production environments.

For more information on proper setup, including the use of the isolated-vm package, read the Enabling data bindings in Node environments in Integration Tips.

Syntax

Use double curly braces to insert state variables:

{{state.someValue}}

Examples

Text Content

You can use data binding for any text content. For example, to create a personalized greeting:

Hello {{state.userName}}!

Link URLs

Data binding also works with hyperlink URLs:

Hello {{state.userName}}!

This feature works with any text content, both in inline text fields and Rich Text Editor (RTE) fields. No additional configuration is required within the Builder interface to use the undefined syntax.

However, to populate these state values with actual data, you need to pass the data to the BuilderComponent in your code, similar to how you pass data for custom actions:

Framework
Meta-Framework
SDK Generation
<BuilderComponent model="page" content={builderJson} data={{ userName: "Ella Jones", linkURL: "https://www.builder.io", }} />

The data passed this way is accessible using state.* in the rich text fields, just as it is in Builder actions and bindings.

What's next

Was this article helpful?