Home App Docs Blog Github

Creating a Symbol with a React Component inside


Two of our teams seem to be struggling with the same issue: Adding React Components to a Symbol, which then does not appear on Builder.io. I’ve linked the threads I’ve tried to follow at the bottom of this post.


We are able to create a Symbol from a React component by using the right-click context menu and selecting “Convert to Symbol”. This works fine on a deployed site, or developing on localhost. It however doesn’t appear on Builder.io.

The Symbol’s content is not visible although still being there. Based on the threads listed below, this is possibly because the preview URL on Builder.io is not linking to the symbol correctly?

I tried to follow Kara’s suggestion from one of the links at the bottom and ended up with:

https://site-url.netlify.app/design-components/?model=symbol where “design-components” is a page with just the symbol on it. The preview for the symbol using this URL dies after a few seconds and shows an ascii face with a dead character expression (two x’s for eyes). I don’t think this URL is close to being correct. I also tried the exact example they had but assumed it wouldn’t work because “builder-editing” needs to be some kind of path that is created either by a page or another method: https://my-site.netlify.app/builder-editing?model=symbol.

This is what Kara said in this thread, which I think is the solution for this: Use a Builderized React component in a symbol

By default, symbols have a generic preview URL. So in your case, you’ll need to add one specific to your site that will load content of the same model name. For example, some people will do something like: our-site.com/builder-editing?model=symbol which renders <BuilderComponent model=“symbol” />

I’m honestly quite a bit lost when trying to understand the solution Kara offers or how this is meant to work as the Symbol(s) I would be editing wouldn’t have a URL?

In my case, I want to have a “Page Header” symbol that contains a parent “Box” container, then nested inside is a React Header component and Banner (Symbol with text being displayed).

These symbols are created on Builder.io, but there’s nothing in the codebase that creates a Symbol. I saw Kara mention that it also needs to exist in the code base so maybe this is where I’m faulting. I tried creating a Builder.io component as a wrapper with type being “symbol” but this didn’t work out either.

Is it possible I could get some guidance on how to correctly use a React component in a Symbol please? Being able to get this working would be a significant improvement for both projects as devs have had to find other ways around the issue.

Thanks for your time.




As as side note. There is no symbol/s tag on the forums so I couldn’t tag this as a symbol

Hey @martink-rsa - so sorry to see this feel off our radar, really appreciate the detailed post.

The core of the issue is your react app needs to provide some way for editing symbols that loads your custom components. For example in Gatsby you could create a page like:

// src/pages/edit-builder-symbol.js

import '../path/to/your/registered/components';

export default function EditBuilderSymbol() {
  return <BuilderComponent model="symbol" />

And then change the “preview URL” for your model symbol to be “https://your-site.com/edit-builder-symbol

To explain the above, we:

  1. Create a route in our app that can render <BuilderComponent model="symbol" /> so we can use that for editing symbol so that instead of the generic URL this runs in our codebase and has access to our registered components
  2. Be sure to import any registered components so this page is bundled with them and will be able to render them
  3. Go to builder.io/models → choose “symbol” → change the “preview url” to point to this page for editing symbols

Lmk if this helps or we can explain better