Using your react components in Builder
Builder allows you and your teammates to use custom react components within Builder. In other words, you write the code for a component, integrate it with Builder, and then anyone creating content within your organization can build with the drag and drop editor is able to use your custom built components.
👉Tip: to skip straight to code examples using custom components with Builder, see our React style guide example repo
Install the SDK
To begin, use npm or yarn to install @builder.io/react.
Configure the SDK with your API key
The examples below are written as if you had configured the SDK to use the same API key for all keys.
You should configure the SDK at the start of your application, typically a file like src/index.js. Near the top of this file, before any other calls to the Builder.io SDK add a call to
builder.init like you see below. Replace YOUR_KEY with the API key found in your organization settings
Builder-Enabling a Component
Below is the actual source for a component we use heavily within our docs, it takes two props, code and "language" and uses react-syntax-highlighter to syntax highlight the code.
This is a normal react component that can be used alone, but we can expose it to the Builder visual editor by registering it with the SDK.
Registering the component with
Builder.registerComponent(...) does two things:
- Makes it appear in the visual editor so you can build pages with it
- Tells the SDK's
<BuilderComponent />to use it for content that was created in the visual editor
options your provide to
registerComponent(component, options) tell the visual editor how your component should appear in the visual editor's library. You can use this to control what icon is displayed and what it's displayed name is - you can find list of other options here.
Make sure that your prop has a matching input for each prop it expects. Listing the inputs allows you to pass data back from the visual editor.
Including the Component
👉Tip: want to limit visual editing to only your custom components? Try components only mode
To use our new
CodeBlockComponent with any of our Builder content we have to import the file to make sure that it's registered before any calls to
BuilderComponent that use it.
The example below assumes that we have a model named "docs-page" that uses our code block. Feel free to create your own model and replace it.
Time to test it out! Visit any page in your web browser that renders this component, if you're using something like react router you could add a new route to the docs page file above.
Here is a more lengthy example demonstrating more input types
The schema of inputs is as follows:
A unique name for this input that should match the equivalent prop name on your react component
Provide text to help the end user with how to fill in this input. Displays below the input to describe or instruct what to enter
An optional default value for this prop. This is useful for showing an example value in the input form when creating a new instance of this component, to better help people using it understand it's purpose
If the input type is "list" you need to include the "subFields" property that is a list of inputs (with this same schema) for each list item
For the "file" input type you typically want to specify what types of files can be uploaded. This is an array that takes content-type files such as:
For any text-based field type, can set a specific set of options that can be used
For any input that results in a string value you can provide a regex to validate user input.
Provide a function that is called whenever the value of the input is updated. Useful for more complex validation than what
The name you would like displayed in the editor for the input
Show and hide the input dynamically.
Using the state of other inputs via
Hide your component from the insert menu within Builder. This can be useful if you are gradually deprecating a component and do not want new content to use it, but still need the component to be registered within Builder so that older content that uses the component will continue to function properly. More info on versioning here
By default Builder wraps your components in a dom element (by default a div but the type of element can be changed) with a few needed attributes and classes for the editor to work as expected.
You can opt out of this wrapping by using the noWrap option. You can see a full code example of this with our built-in form input component here
For sake of example here, if you say wanted to use a Material UI TextField in Builder.io with noWrap
If you would like your components to have some default CSS styles applied, that can be edited in the
style tab, you can set default styles like in the example below
Using your components in the editor
To use your components in the editor, make sure you first follow this guide to allow editing and previewing directly on your site
Then, when editing a page in Builder that imports components with the withBuilder function, they will display in your "insert" tab in a "code components" section.
Developing and testing locally
When developing locally, you'll want to update the preview URL in the top right corner of the preview from your production URL to your local development URL.
Note that when developing locally you are mostly likely developing on a non-ssl http:// url within Builder, which is an https:// site. Browsers don't allow https:// sites to make insecure http:// requests unless you explicitly allow it
On chrome, to allow access to your local http URL choose the shield icon on the right side of your URL bar, and then choose "load unsafe scripts". The page will reload and you may have to enter your local URL a second time, but this time chrome will allow it's content to load
Server side rendering (SSR) and static site rendering (SSG)
Builder supports SSR and SSG out of the box for all components.
The only thing you may need to account for is if you have custom components that depend on external data sources (e.g. a products API) that need that data server side.
Here is a usage example with Next.js
Children in custom components
You can also have children within your Buider.io components (limited to specific child options or any type of child). Note the use of
withChildren() below - this will allow this component to have children dropped into it
If you want to be fancy and only allow certain types of children, you can do this with
childRequirements like in this example
Advanced child sub-component use cases
For use-cases where you need multiple sets of children rendered - e.g. making your own custom tabs components, see our built-in tabs component source code here. More examples of component source code with multiple children
▶ Expand code example
👉Tip: You can see a detailed answer to advanced React children use cases with code examples over in our forum!
Versioning and Deprecating Custom Components
Eventually you might need to make changes to custom components that are already in use within content your team has created. We recommend that any changes made to your components are backwards compatible with existing content so that any content using the old version of the component will continue to function properly. This is because although the content was originally created with the old version of the component, when Builder renders the content on your site it will use the current version of the custom component, since that is what version exists on your site. For example, if the new version of the custom component has an additional input, make sure to handle the case where that input is
undefined, since old content will not have a value for that input. Note: if a
defaultValue is passed to an input will only be applied to new content created that uses the new component, it is not retroactive.
Sometimes the changes you need to make cannot be backwards compatible. In that case, the best approach is to create an entirely new component registered with a new name. You will still want to register the old version of the component with Builder so that existing content on your site using the component will continue function properly, but you might want to hide the old component from the Builder editor so people on your team do not use the old version with newer content. To do that, use the
hideFromInsertMenu option when registering the component.
Input type examples:
string: any text, usually shorter in length and unformatted
number: an input field expected to take a number such as an amount
boolean: an input field taking true or false
longText: same as string type but with a multiline text field editor. (if formatted, use richText)
richText: Displays a rich text editor and provides the value as html
file: Uploads a file and provides the value as a url string. See allowedFileTypes for additional details.
color: provides a color value (hex or rgb) to a component
email: create an email value for a component
object: a set of specific names and values
*note: you will get errors if no defaultValue is set for objects
list: list of items
*note: you will get errors if no defaultValue is set for lists
Want to limit page building to only your custom code components? Try out components-only mode
Don't use React?
Try using symbols for the same level of functionality and symbols support any framework!