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, like below (substituting the name "page" for the name of your model, if it is not the built in "page" model):
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 thir 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, like localhost:3000/builder-editing until your live site with the Builder integration is deployed, then 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, any Builder component on your page will send a message to us notifying that it has been found. This will only occur 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.
First, is to add the Builder component to your 404 page, to support previewing and editing.
The second, 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 (e.g.
/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
To know if this is the issue you are facing, open your browsers developer tools and check for errors that suggest content from Builder is being blocked, for instance like this:
You can also try enabling our site proxy to try and handle this for you 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
here for Firefox
If still no luck, try contacting our support
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.
More 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 (e.g. your-site.com/builder-editing).
To troubleshoot - check on any conditional logic in your code that might prevent the relevant Builder component from loading under certain conditions, e.g. for instance 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.isEditing and 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