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

Using BuilderComponent

The BuilderComponent from Builder's Gen 1 SDK is how you specify where in your app you want to feature Builder content. It offers a number of props to help you specify exactly what to render in your integrated app.

Recommended usage

When using BuilderComponent :

  • You must specify the model.
  • We highly recommend that you also pass content.
<BuilderComponent model="page" content={contentJSON} />

Props

Props are key to customizing component behavior and managing content. With BuilderComponent props, you can define how the component interacts with Builder, control content sources, and pass necessary data or context.

model

required

Alias: modelName

Use to specify the name of the Builder model whose content this component is rendering. This is often a Page or Section model. If you had a model named announcement-bar, for example, you'd pass that in. In this example, the model is page.

<BuilderComponent model="page" ... />

For more information, visit Introduction to Models.

content

optional but recommended as a best practice

Explicitly specify the Builder content JSON object to render. Helpful for server-side rendering or custom content fetching logic.

<BuilderComponent model="page" content={contentJSON} />

For more information, visit Content API.

data

optional

Use to pass custom data into the rendered Builder content. This is an object containing data passed to the Builder component, accessible in the Visual Editor. Enables dynamic content rendering by passing different data based on application state or user interaction.

<BuilderComponent model="page" data={{ myVar: 'Hello' }} />

For more information, visit Data Models and Building Interactivity Using State and Actions.

context

optional

Use to provide an object available in actions and bindings inside Builder.io. Helpful for passing additional context or global data for use in Builder.io's actions and data bindings.

<BuilderComponent model="page" context={{ user: 'Marie Lorenzo' }} />

stopClickPropagationWhenEditing

optional, for advanced use cases

Set to true to prevent event.stopPropagation() in the Visual Editor. This method is essential in scenarios where the default event propagation behavior interferes with intended interaction.

<BuilderComponent model="page" stopClickPropagationWhenEditing={true} />

locale

optional

Set the locale in your <BuilderComponent> as a prop to match one of the locale keys configured in Space Settings. This ensures localized inputs are automatically resolved based on the user's locale. To learn more, see Adding Locales.

To ensure content renders properly on your site, set the locale in both the builder.get() API call and the <BuilderComponent>.

// 1. add the locale in builder.get() const localizedContent = await builder .get(modelName, { // other fields // When content is localized through Targeting, // the locale should be passed to the userAttributes userAttributes: { locale: "en-US" }, // When content is localized in-page, // the locale should be passed directly to the options options: { locale: "en-US" } }).toPromise(); // 2. Pass the **locale** as a prop to provide component level context. <BuilderComponent locale="en-US" model={modelName} content={localizedContent} />

This setup helps deliver content tailored to different languages and regions using locale-specific configurations. To learn more, see Content entry localization.

Methods

Helpful for advanced content handling and user interaction, BuilderComponent methods handle events and actions for advanced control and interactivity.

contentLoaded

optional

A callback function that is invoked when the Builder content is successfully loaded. Helpful for adding logic or state updates on load.

<BuilderComponent model="page" contentLoaded={(data, content) => console.log('Content loaded!', content)} />

For more information, visit Building Interactivity Using State and Actions.

contentError

optional

A callback function that is invoked if an error occurs while fetching the content. Provides a way to handle errors gracefully, such as displaying a user-friendly message or fallback content.

<BuilderComponent model="page" contentError={(error) => console.error('Error loading content', error)} />

onStateChange

optional

A callback that runs when the Builder state changes, like from user interactions or dynamic content updates. In this way, your app can respond to dynamic changes in the application state for more interactive and responsive user experiences.

<BuilderComponent model="page" onStateChange={(newData) => console.log('State changed', newData)} />

For more information, visit Building Interactivity Using State and Actions.

renderLink

optional

Provides a custom component for handling links throughout your Builder content. This prop is important for supporting client-side routing in single-page applications (SPAs), preventing full Page reloads when navigating between Builder Pages.

Your custom link component can receive all attributes that an HTML anchor tag can receive, with href and target being the most common. Here are examples for React and Next.js:

Here is an example for React:

// React example function CustomLink(props) { return <a {...props} /> }

Here's a Next.js example:

// Next.js example import Link from 'next/link' function CustomLink(props) { return <Link {...props} /> }

Then use renderLink in BuilderComponent:

<BuilderComponent model="page" renderLink={(props) => <CustomLink {...props} />} />

Your custom link can receive all attributes that an HTML anchor tag, <a>, can receive, with href and target being the most common.

renderLink is equivalent to the linkComponent prop in Gen 2 SDKs. For details, visit the linkComponent entry in Using the Content Component.

Legacy props

While legacy props like builder, entry, and options are part of the component's history, their usage is no longer recommended. For optimal performance, use the content prop in conjunction with server-side data fetching with builder.get() as documented in Content API and in the Querying Cheatsheet.

Theses legacy props are provided here only for reference.

builder

A specific instance of the Builder class.

<!-- DO NOT USE --> <BuilderComponent builder={customBuilderInstance} />

entry

The content entry ID to fetch for rendering.

<!-- DO NOT USE --> <BuilderComponent model="page" entry="your-entry-id" />

options

Options for fetching content, including custom targeting and query parameters.

<!-- DO NOT USE --> <BuilderComponent model="page" options={{ cachebust: true }} />

What's next

For more information on fetching content, visit Content API.

Was this article helpful?