Join us for our biggest AI launch event on 10/31

Announcing Visual Copilot - Figma to production in half the time

Builder.io logo
Contact Sales
Platform
Developers
Contact Sales

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

Explore the power of server-side pre-rendering and seamless integration with any tech stack using the Builder HTML API.

To experiment with the HTML API, check out the Builder API Explorer, which works with your own Builder content. The following video shows an example of using the API Explorer:

The following is an example of a request and response:

https://cdn.builder.io/api/v3/html/YOUR_MODEL_NAME?apiKey=YOUR_API_KEY&url=PAGE_URL

# Example response
# {
#   "id": "c923kd89",
#   "name": "About page",
#   "data: {
#     "html": "<div data-builder-component="banner-ad"><div class="builder-blocks"><h1>Hello!</h1></div></builder-div>"
#   }
# }

Tip: Custom components work in all of Builder's supported frameworks except for the HTML API.

NameRequiredDescription

apiKey

Yes

url

No

The current URL of the visitor on your site.

?url=https://your-site.com/about?foo=bar

includeUnpublished

No

Set to true to include unpublished content in your API response; for example, testing.

query.*

No

Mongodb-style query of your data.

&query.data.id=abc123
&query.data.myCustomField=someValue
&query.data.someNumber.$ne=20

fields

No

Only include these fields.

&fields=id,name,data.customField

omit

No

Omit only these fields.

&omit=data.bigField,data.blocks

userAttributes.*

No

Optionally use this to send targeting attributes.

&userAttributes.device=desktop
&userAttributes.locale=en_us

cacheSeconds

No

Seconds to cache content (sets the max-age of the cache-control header response header). Set the value higher for better performance and lower for content that changes more frequently.

&cacheSeconds=120

format

No

Set to amp to render amp content (the content must be made with an amp model type) or email to render email model content (the content must be made with an email model).

&format=amp

As you work, it is essential to preview the content you build on your actual site. This ensures that any side effects of site-wide styles that affect Builder-created content—for example, heading CSS rules—are accurately displayed.

To integrate previewing:

  1. Create a single route on your website that serves the Builder preview HTML and JavaScript by creating a new page/endpoint/route on your site called, for example, /builder-preview.

If you name the route something other than /builder-preview, replace /builder-preview in any example code and settings to the path you choose.

Your framework determines how to create the new route, but the HTML it returns should be similar to the following example:

<builder-component model="PAGE_MODEL_NAME" api-key="YOUR_API_KEY"></builder-component>
<script async src="https://cdn.builder.io/js/webcomponents"></script>

Tip: Make sure to replace the PAGE_MODEL_NAME and API_KEY with the actual values from your Builder space.

For more information, read Using Builder API Keys and Page Models.

Change the PAGE_MODEL_NAME to the Builder model name of the model you want to preview—oftenm, it is page. An alternative and useful approach is to not hardcode the model name, but instead to have it be determined by query parameter in the page URL.

In this way, you can use a single endpoint to preview content from different models, such as /builder-preview?model=page or /builder-preview?model=homepage-section. Here is a pseudocode example:

import layout from '../yourLayoutComponent';
import { builderPublicKey } from '../constants/builder';

const model = requestQueryParams.get('model');

return (
  <layout title="Builder.io Preview page">
    <builder-component name="{model}" api-key={builderPublicKey}>
    </builder-component>
    <script src="https://cdn.builder.io/js/webcomponents" async></script>
  </layout>
);

For more information, read Dynamic Preview URLs.

Next, set the model Preview URL in Builder:

  1. Go to Models.
  2. Select the model you want to integrate previewing with. Change the preview URL to https://www.yoursite.com/builder-preview (make sure to replace that with your actual website).
  3. Click the Save button.

For more context, read Editing and Previewing Your Site.

Tip: If you decided to have the model name determined dynamically, then change the Preview URL to have a model query param and have that value be the name of the model; for example, https://www.yoursite.com/builder-preview?model=page

  1. Go to Account Settings.
  2. Go to Advanced Settings > Advanced.
  3. Toggle off the setting called Reload preview on URL path change. This setting is on by default, so you need to click it to make it turn grey instead of blue, which coincides with the toggle to the left.

You should now be able to create content in the editor and preview it on your site. Repeat this process as needed with other models you'd like to preview on your site.

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

Product

Platform Overview

Integrations

What's New

Open Source

Builder

Builder

Mitosis

Mitosis

Qwik

Qwik

Partytown

Partytown

Popular Guides

From Design to Code Guide

Composable Commerce Guide

Headless CMS Guide

Headless Commerce Guide

Composable DXP Guide

Design to Code

Resources

Blog

Knowledge Base

Community Forum

Partners

Templates

Success Stories

Showcase

Resource Center

Frameworks

React

React

Next

Next.js

Qwik

Qwik

Gatsby

Gatsby

Angular

Angular

Vue

Vue

Svelte

Svelte

Remix logo

Remix

Nuxt

Nuxt

Hydrogen

Hydrogen

See All

© 2024 Builder.io, Inc.

Security

Privacy Policy

SaaS Terms

Security & Compliance

Cookie Preferences