Live Previewing Data Models and Custom Fields

With the React SDK, you can use live previews to render edits in your data model without having to publish.

Although you can already fetch data models from Builder's Content API directly and use it as you would any other API resource, with the BuilderContent component, you can use features such as live editing, previewing, and A/B testing of your Data Models within the Builder Visual Editor, all while using standard JSX syntax.

Prerequisites

To get the most out of this document, you should already be familiar with:

Tip: Live Previewing data models is currently supported in Builder's Gen 1 React SDK with active development in the Gen 2 React SDK. For details on the SDKs, read SDK Comparison.

Gen 1 SDKs: getting your data in `BuilderContent`

Specify the name of your data model in BuilderContent with the model prop.
Use a render prop pattern with the required data parameter, an optional loading parameter, and a content parameter if you're using SSR.
In the return() statement, add code that accesses your data. This code varies and depends on your use case.
Set the Preview URL on the data model. For detailed instructions on setting a Preview URL on a model, visit the Setting a persistent Preview URL on a model in Editing and Previewing Your Site.
Test the live preview by editing your data model in the Builder Visual Editor and checking that the changes are reflected in your application.

The following snippet shows this structure.

// Add your data model's name
<BuilderContent model="YOUR_DATA_MODEL"> 
  // add function to render data
  {(data, loading, content) => {
    if (loading) return <div>Loading...</div>;
    return (
      // Add your code to access your data
    );
  }}
</BuilderContent>

This example uses a custom data model called site-settings, which includes a navigationLinks field of type list. Each link contains a linkURL and linkText sub-field.

import { BuilderContent } from "@builder.io/react";

export const Navigation = (props) => {
  return (
    <BuilderContent model="site-settings">
      {(data, loading, fullContent) => {
        if (loading) {
          return <div>Loading...</div>;
        } else {
          return (
            <>
              <ul>
                {data?.navigationLinks?.map((link) => {
                  return (
                    <div key={link.linkUrl}>
                      <a target="_blank" href={link.linkUrl}>
                        {link.linkText}
                      </a>
                    </div>
                  );
                })}
              </ul>
              {props.children}
            </>
          );
        }
      }}
    </BuilderContent>
  );
};

The BuilderContent component uses the site-settings data model to fetch the most recent published entry of the site-settings model for rendering. The inline function takes three parameters, data, loading, and fullContent.

data (required): the resolved data from the Builder content. in this case is the structured data from the most recent entry of the site-settings model. If you’re using A/B testing, BuilderContent automatically returns the winning variant without additional configuration.
loading (optional): boolean indicating if the data is still loading.
fullContent (required for SSR): the raw data that the Content API returns, containing all A/B variations and metadata. If you use client-side rendering and don’t pass in a content prop to BuilderContent, BuilderContent selects the most recent published entry of the model specified.

The video below shows using this example data model in the Visual Editor:

An example with blog custom fields

This example uses a custom section model called blog-article, which includes a title, author, handleandpublishedDatefields, each of type text. This example uses the page router paradigm from NextJS to achieve Server Side Rendering

import { BuilderComponent, BuilderContent } from "@builder.io/react";

export async function getStaticProps({ params }) {
  const article = await builder
    .get("blog-article", {
      // Include references, like our `author` ref
      options: { includeRefs: true },
      query: {
        // Get the specific article by handle
        "data.handle": params.handle,
      },
    })
    .promise();

  return {
    props: {
      article,
    },
  };
}
function BlogArticle({ article }) {
  return (
    <BuilderContent
      content={article}
      options={{ includeRefs: true }}
      model="blog-article"
    >
      {(data, loading, fullContent) => (
        <>
          <div>{data.title}</div>
          <div>By: {data.author}</div>
          <div>Published: {data.publishedDate}</div>
          {/* Render the Builder drag/drop'd content */}
          <BuilderComponent
            name="blog-article"
            content={fullContent}
            options={{ includeRefs: true }}
          />
        </>
      )}
    </BuilderContent>
  );
}

On the server, builder.get() fetches a published entry of the blog-article model based on the handle passed from params. On the client, we pass the article data object to the BuilderContent component to render. The inline function takes three parameters, data, loading, and fullContent.

data (required): the resolved data from the Builder content. in this case is the structured data from the blog-article model. If you’re using A/B testing, BuilderContent automatically returns the winning variant without additional configuration.
loading (optional): boolean indicating if the data is still loading.
fullContent (required for SSR): the raw data that the Content API returns, containing all A/B variations and metadata. If you use client-side rendering and don’t pass in a content prop to BuilderContent, BuilderContent selects the most recent published entry of the model specified.

The title, author, publishedData fields can now update in realtime within the visual editor without having to publish any changes. And by using a BuilderComponent component to render your drag and drop content, you still have the flexibility to create visual layout for your blog entry.