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} />

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?