Resources

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

Forum

Blog

Github

Signup

Made in Builder

Using custom React components in Builder

Check out our step-by-step tutorial

Try our tutorial with detailed instructions on how to use your custom React component in Builder.

When you integrate your custom React components with Builder, anyone creating content within your organization can use your custom components with the drag-and-drop editor.

👉 Don't use React? You can register custom web components with any framework or stack. See the Builder Webcomponents Full API article. Or use symbols to create reusable components directly in Builder

Installing the SDK

In your project, use npm or yarn to install @builder.io/react.

Configuring the SDK with your API key

The JavaScript SDK needs your API key to fetch your content hosted on Builder.io.

The examples below configure 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 such as src/index.js. Near the top of this file, before any other calls to the Builder.io SDK, add a call to builder.init() as in the following example. 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 the Builder.io docs. It takes two props, code and language , and uses react-syntax-highlighter to syntax highlight the code.

This is a regular React component that we could use alone, but we can expose it to the Builder visual editor by registering it with the SDK.

Registering a component with Builder.registerComponent(...) does two things:

  1. Makes the component appear in the Visual Editor so you can build pages with it.
  2. Tells the SDK's <BuilderComponent /> to use it for content that created in the Visual Editor.

The options you 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 Builder displays for your component and what its displayed name is. For a list of other options, see Input types.

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

To use CodeBlockComponent with any of our Builder content, we have to import the file to make sure that it's registered before the code makes any calls to BuilderComponent.

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.

👉Tip: To limit visual editing to only your custom components, use components only mode.

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.

Input types

Here is a more detailed example demonstrating more input types:

The schema of inputs is as follows:

NameRequiredDescription

name

Yes

A unique name for this input that should match the equivalent prop name on your React component.

type

Yes

Types correlate to what editing UI is appropriate to edit this field. Common types include:

View detailed info on input types

You can also add custom types here via plugins.

helperText

No

Provide text to help the end user know how to fill in this input. Displays below the input.

defaultValue

No

An optional default value for this prop. 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 its purpose.

subFields

No

If the input type is list , you must include the subFields property that is a list of inputs, with this same schema, for each list item.

allowedFileTypes

No

For the file input type, specify what types of files users can upload. This is an array that takes content-type files such as:

enum

No

For any text-based field type, you can specify a set of options that the field can use.

regex

No

For any input that results in a string value you can provide a regex to validate user input.

onChange

No

Provide a function that is called whenever the value of the input is updated. Useful for more complex validation than regex or running custom logic when an input value updates.

friendlyName

No

The name the Editor displays for the input.

showIf

No

Show and hide the input dynamically. options is an object with the current options, that is, values from inputs, that are set on the component. parent is the component definition, and parentElements is an array of all the parent elements of where the component is placed. For example, to only show the input if the component is inside of a Columns component has the input myInputOption set to true, you could write a function as follows:

Using the state of other inputs via options is a useful way to hide or show inputs that depend on one another. For example, you could show an input that opens a link in a new tab only if a link is present, instead of always showing all inputs and potentially confusing content creators who are using the component.

hideFromInsertMenu

No

Hide your component from the insert menu within Builder. This can be useful if you are 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 continues to function properly. For more information on versioning, see the Versioning and deprecating custom components section.

noWrap

No

By default, Builder wraps your components in a div.

You can opt out of this wrapping by using the noWrap option. For a full code example, see our built-in form input component.

The following example shows noWrap with a Material UI TextField in Builder.io.

Setting default styles for custom components

Configure the default CSS styles for your components, which content creators can edit in the Style tab. Set default styles as follows:

Using your components in the Editor

To use your components in the editor, make sure you first follow the guide for Editing and previewing directly on your site.

When editing a page in Builder that imports components with the withBuilder() function, the components display in the Insert tab in a Code Components section.

Developing and testing locally

When developing locally, 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.

To allow access to your local http URL in Chrome, click the shield icon on the right side of your URL bar, and then choose "load unsafe scripts". The page will reload and you might have to enter your local URL a second time for Chrome to allow its content to load.

Server side rendering (SSR) and static site rendering (SSG)

Builder supports SSR and SSG out-of-the-box for all components.

If you have custom components that depend on external data sources and need that data server-side, such as a products API, use Builder's getAsyncProps utility to fetch any data needed server-side before render.

The following is a Next.js example:

For more information on server-side data, see the getAsyncProps README.

Adding children to custom components

You can have children within your Buider.io components. You can have any type of child, or you can limit children to specific child options. Note the use of withChildren() in the following example, which allows this component to have children.

If you want to allow only certain types of children, you can configure childRequirements as in the following example:

To test your component, visit any page in your web browser that renders this component. If you're using routing, such as the React router, you could add a new route to the docs page file above.

Advanced child sub-component use cases

For use cases that need to render multiple sets of children, such as making your own custom tabs components, see Builder's built-in tabs component source code.

Some examples of component source code with multiple children include:

▶ 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

When you make changes to custom components that are already in use, we recommend that any changes you make to your components be backwards compatible with existing content. This way any content using the old version of the component continues to function properly.

Builder uses the current version of the custom component when rendering your content since that is the version that exists on your site, even if the content was originally created with the old version of the component.

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 does not have a value for that input.

Note: If a defaultValue is passed to an input, Builder only applies that value to new content that uses the new component–it is not retroactive.

If the changes you need to make cannot be backwards compatible, the best approach is to create an entirely new component registered with a new name.

You still need to register the old version of the component with Builder so that existing content on your site using the component continues to function properly. However, hide the old component from the Builder editor so your team doesn't use the old version with newer content.

To do hide a component, use the hideFromInsertMenu option when registering the component.

👉Note: Content model backing the component does not update automatically.

Input type examples:

string: any text, usually shorter in length and unformatted

alias: text

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

alias: 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

date: any format that the date constructor for Javascript takes

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

alias: array

*note: you will get errors if no defaultValue is set for lists

Components-only mode

To limit page building to only your custom code components use components-only mode.

Don't use React?

Even if you use any other framework, you can get the same level of functionality by registering custom web components or using symbols.

Was this article helpful?