Builder is a Visual Headless CMS. You determine which parts of your app that non-developers can create and manage. Builder passes data to your site or app using various SDKs and APIs and allow you to publish content over an API or generate code you work into your codebase.
Builder doesn't host your site for you, but gives you the tools to dynamically load content created in Builder into your code. You have complete control as to what you want to be Builder-editable and where.
You control the structure of your site with models. You can customize where content of each model loads, how it is targeted and filtered, and where and how it is rendered.
To get up and running with an integrated app, see the Developer Quickstart.
In many ways, Builder works the same as any headless CMS, and Builder's CMS data models work identically.
Like a typical headless CMS, you create entries with structured custom fields or targeting. You can then query these fields with our content API and display the content you want, where you want.
In many cases with Builder, the main difference is instead of hard coding a page layout, you have a Builder renderer component render the content dynamically, optionally using components from your codebase.
Optionally, you can also restrict Builder editing to only these components—with or without allowing custom styling—using components-only mode and/or roles and permissions.
The next image shows how integrating your app can remove hard-coded content best maintained by other roles on your team, such as marketers, and copywriters.
In addition to visual editing, Builder also adds additional features that are less common in traditional headless CMSes, such as content targeting and analytics.
Structured CMS data has its purposes, and while it often isn't the best for things like pages and layouts, it can be great for a number of other use cases that structured data can be more ideal than pure visual editing.
Under the hood, Builder is a headless CMS like any other. You can create documents with structured data fields and consume these via our SDKs and APIs and render the data as you choose.
On top of this, Builder adds even more power by letting you register components that can render dynamically, saving you from having to write all of this logic manually. Instead, you can pass the data to a render Builder provides, such as in the following snippet:
<BuilderComponent model="page" content={json} />For pages and sections, Builder automatically populates a field called blocks that is a list of components to render and their options, as in the following snippet:
{
"data": {
"yourCustomFieldName": "yourCustomFieldValue",
"blocks": [
{
"component": {
"name": "Text",
"options": {
"text": "Hello world!"
}
}
}
]
}
}Builder passes this data to your site or app via various APIs, and you can load it into your site as HTML or rendered dynamically via this JSON with frameworks such as React.
The Visual Editor loads your site in an iframe. You provide the URL for the editor to open. This page needs to have a Builder SDK integrated so Builder can discover where it is, any settings provided, and pass messages to it.
When a Builder SDK is loaded in the editor, instead of showing the default content, the SDK waits on a message from the Builder web app of what content to display. Builder messages down the JSON and send patches as edits are made of what to render differently—such as added components or changed inputs—and the SDK renders the updates accordingly.
You can also register your own components to use in the editor. When you register your own components, Builder keeps a map of component names to references, and messages the web app what components exist and what inputs they take. Within Builder, the built-in components—such as Image, Text, and Columns—work the same way and are open source.
// This code is in your app. Can be the same components you already use
import { Builder } from '@builder.io/react';
const Heading = (props) => <h1>{props.text}</h1>
Builder.registerComponent(Heading, {
name: 'heading',
inputs: [{ type: 'string', name: 'text' }]
})Internally, Builder keeps a map such as this one:
const componentMap = {}
componentMap['heading'] = HeadingAnd then when Builder renders the content, Builder iterates over the blocks and render the components and inputs in your framework/SDK of choice, as in the example below:
// Simplified example
export const BuilderComponent = (props) => (
props.blocks.map(component => {
let Component = componentMap[component.name];
return <Component {...component.options } />
})
)You can see examples on how to implement your own rendering for any language or framework in this forum post.
Builder.io loads your website in an iframe in Builder's web application.
When your page loads in Builder's web app, any Builder component on your page sends a message to Builder notifying that it has been found. This only occurs for a matching component; for instance, if you are opening a page to edit your Page model, Builder waits for a message from a component whose model is Page. Once received, Builder sends a message for what content should be rendered for the preview.
As you click around and make edits, Builder continuously passes messages to this component telling it what new changes to reflect.
If Builder never receives a message from a component of the model type you are trying to edit, Builder doesn't know where or how to preview your content, so you need to ensure the right component loads on the right page. See our troubleshooting section for more info.
Builder integrates with your front-end code, not with your hosting platform, and pushes content to your site or app using APIs or generated code. You control your site, code, and hosting—Builder only passes content within your own setup.
If your app is currently deployed, works on your host server, and you integrate Builder into your app, Builder works seamlessly with your code, and you are still free to use your choice of hosting provider.
Examples of hosting providers that Builder customers use include Netlify, Vercel, Amazon AWS, and Google Cloud.
All content is delivered from the edge, renderable server-side or statically, and we optimize the heck out of it. And our SDKs are small and mighty.
Importantly, there are no hacks here—no iframes, no unneeded client-side code or rendering. Builder's guiding principle is that we produce content just as if you'd written it by hand. Assets are optimized, DOM is minimized, and it's all native to your framework. That is, if you use React, all components are React, and so on, for each framework.
Or for instance, take a look at the perf of the Builder.io site, which is built completely in Builder:
In addition to being able to register your own components in the editor and using Components-only mode, you can also Extend the Builder UI with plugins for deep customization.
Builder gets its structure from models. You can make additional models for Pages, Sections, and Data, and customize them with custom field types as well as plugins.
Visual Pages
Use Pages to manage entire pages, such as:
- Marketing and content pages
- Landing pages
Structured Data
Use Structured Data to manage structured data, such as:
- Navigation links
- Product details
- Blog post authors
In addition to taking a look at our docs and SDKs, you can always post questions on the Builder forum where Builder's technical team is available to help you out.
For more information on structuring your app, see:
- Builder Best Practices: pointers on how to use the Visual Editor. Great for non-developers on your team.
- Architecture Best Practices: guidelines for how to structure your app and decide what goes in Builder and what goes in your code.
