Editing and Previewing Directly on Your Site
Enabling editing directly on your site is important for accurate previewing and editing, to inherit your site styles, fonts, and components.
The first thing you need is to integrate Builder onto your site or app.
Next, we need a URL that will always render the Builder component or code snippet above. This could, for example, mean hard-coding a certain url, like
your-site.com/builder-editing that will always have the above code loaded, even if Builder has no actual content matching for the given URL.
👉 Note: When using the HTML API, you will need to pass
?url=/__builder_editing__ to return a valid code snippet for the given page when editing. For all other SDKs and frameworks you just need to make sure the Builder component that renders content is rendered onto the page.
Then, go to builder.io/models, select the model you just integrated (for instance the
page model), and enter the URL for the Editing URL field.
Once you save this URL, it will be used when editing content of this model in Builder.
✨ Note: When working locally, you can set the editing URL to be a local one, such as
localhost:3000/builder-editing until your live site with the Builder integration is deployed. At deployment time, you can change the preview URL to be your production or a staging site.
How does this work?
Builder.io loads your website in an
iframe in our web application.
When your page loads in our web app, Builder components on your page send a message to us 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, we wait for a message from a component whose model is page. Once received, Builder sends a message down for what content should be rendered for the preview.
As you click around and make edits, Builder continuously passes messages down to this component telling it what new changes should be reflected.
If Builder never receives a message from a component of the model type you are trying to edit, we don'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.
For static sites, such as with Gatsby, Nuxt, or Next.js in static mode, you may want to have a couple additional considerations.
By default, when creating a page and editing it in Builder, the editor and preview will try to load on the URL for that page. For example if you create a new page at
/example but your static site has no such page, you may just get a 404. There are two options for this scenario.
The first option is to add the Builder component to your 404 page, to support previewing and editing.
The second option is to disable this behavior of trying to preview and edit on the specific URL for a page. In your space settings, in advanced settings, in the advanced tab, there is an option called Reload preview on URL path change. You can turn this off to load the preview and editor on your hardcoded URL–for example,
/builder-editing –regardless of the current editor path.
Iframe not loading
Builder's visual editor loads your website in an
iframe. This means your website needs to allow Builder to do this, so if you are using headers that block iframes from loading like
content-security-policy, you'll want to either allow
https://builder.io or install our chrome extension.
To know if this is the issue you are facing, open your browser's developer tools and check for errors that suggest content from Builder is being blocked. A common error logged to the console might be:
❌ Refused to frame because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'self'".
You can also try enabling our site proxy to handle this automatically. To do so, go to builder.io/account/space -> advanced settings -> advanced tab -> turn proxy previews on.
If that doesn't work as hoped, try turning it back off and installing our chrome extension to see if that allows editing as expected for you.
Additionally, if you are working on developing your site locally, e.g. on
http://127.0.0.1, you may need to be sure to tell your browser it's ok to load your local site which is using
http, an insecure protocol, within our
https (secure) app. See how to do this here for Chrome and here for Firefox.
In some cases, you may need to manually configure your server technology's Content Security Policy to permit loading the project in an iframe. The below header will instruct a localhost:3000 server to allow loading in an iFrame and in Builder.io:
Code not found
If Builder has trouble loading your site in the editor, try opening that same page on your site and ensure the page loads as expected and the Builder component has rendered. For instance if using a framework like React, you should see
<BuilderComponent /> or
<BuilderPage /> rendered on the current page with React devtools.
With most other integrations, you should see a
<builder-component> tag in the page's HTML.
If you do not see the relevant code, check your integration for conditions that are not met. For example, if your code has logic that says if Builder has no such content for a URL to render something else, be sure to update your code to still show the Builder code component or snippet anyway for your hardcoded editing route, such as
To troubleshoot, check on any conditional logic in your code that might prevent the relevant Builder component from loading under certain conditions. For example, for a page URL that has no live content yet but we still need our component to load for editing in the iframe in the Builder.io editor for receiving messages from our web application to display and preview content in real time.
You can use
Builder.isPreviewing to help out here.
BuilderComponent might not render when editing due to conditional logic in this code
Check for Builder.isEditing to always render BuilderComponent when editing