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

☰

Home

Forum

Blog

Github

Login

Signup

Made in Builder

Using your react components in Builder

Using your own React components in Builder is one of our most powerful features! Learn how below.

πŸ‘‰Tip: for a lot of examples of using custom components with Builder.io, see our React style guide example repo!

Install the SDK

To begin, use npm or yarn to install @builder.io/react.

npm install --save @builder.io/react

Configure the SDK with your API key

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

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

// src/index.js

import { builder } from '@builder.io/react';

builder.init("YOUR_KEY");

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:

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

The 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.

// src/CodeBlockComponent.jsx

import * as React from "react";
import SyntaxHighlighter from "react-syntax-highlighter";
import { Builder } from "@builder.io/react";

export const CodeBlockComponent = (props) => (
  <SyntaxHighlighter language={props.language}>{props.code}</SyntaxHighlighter>
);

Builder.registerComponent(CodeBlockComponent, {
  name: "Code Block",
  inputs: [
    {
      name: "code",
      type: "string",
      defaultValue: "const incr = num => num + 1",
    },
    {
      name: "language",
      type: "string",
      defaultValue: "javascript",
    },
  ],
});

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.

// src/DocsPage.jsx

import { BuilderComponent } from '@builder.io/react';

import './CodeBlockComponent'

export const DocsPage = () => (
  <BuilderComponent modelName="docs-page" />
)

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.

<Route path="/c/docs" exact={false} component={DocsPage} />

Input types

Here is a more lengthy example demonstrating more input types

const CodeBlockComponent = ({text, toggle, image, exampleList}) => <>/* ... */</>;

Builder.registerComponent(CodeBlockComponent, {
  name: "My Cool Code Block Component",
  inputs: [
    { name: "text", type: "string" },
    { name: "toggle", type: "boolean" },
    { name: "image", type: "file", allowedFileTypes: ["jpeg", "png"] },
    {
      name: "exampleList",
      type: "list",
      subFields: [{ name: "text", type: "string" }],
    },
  ],
});

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 should be used to edit this field. Common types include

'string'
'number'
'boolean'
'longText' // String type but with a multiline text field editor
'richText' // Displays a rich text editor and provides the value as html
'file' // Uploads a file and provides the value as a url string
'color'
'date'
'email'
'object'
'list'

VIEW DETAILED DOCS ON INPUT TYPES

You can also add custom types here via plugins

defaultValue

No

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

subFields

No

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

allowedFileTypes

No

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:

allowedFileTypes: ['jpeg', 'png', 'mp4', 'gif', 'pdf', 'svg']

enum

No

For any text-based field type, can set a specific set of options that can be used

enum: ['option 1', 'option 2']

regex

No

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

 regex: {
    // pattern to test, like "^\/[a-z]$" 
    pattern: "^\/[a-z]$",
    // flags for the RegExp constructor, e.g. "gi"  */
    options: "g",
    // message to display to end-users if the regex fails
    message: "You must use a relative url starting with '/...' "
  }

onChange

No

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

// Example of how to validate and limit the length 
// of a list input called myList
// 
// Note: the function is stringified and evaluated in 
// the context of the parent window, 
// so don’t try to use any references to other 
// variables or functions that you might have 
// within the file that your component defined
onChange: (options) => {
  if (options.get('myList').length > 6) {
    options.set('myList', options.get('myList').slice(0, 6))
    alert('maximum items is 6, delete items to continue')
  }
}

friendlyName

No

The name you would like displayed in the editor for the input

friendlyName: 'Open link in new tab',

showIf

No

Show and hide the input dynamically. options is an object with the current options (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 and has the input myInputOption set to true, you could write a function like this:

showIf: (options, parent, parentElements) => {
  return options.get('myInputOption') && parentElements.some(el => el && el.component && el.component.name === 'Columns');
}

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

πŸ‘‰ For more detailed examples of input types, click here

Default Styles

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

const HeloWorldComponent = (props) => <div>{props.text}</div>;

Builder.registerComponent(HeloWorldComponent, {
  name: "Hello World",
  defaultStyles: {
    textAlign: "center",
    fontSize: "20px",
  },
  inputs: [{ name: "text", type: "string" }],
});

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.

For this we have a getAsyncProps utility, to fetch any data needed server side before render.

Here is a usage example with Next.js

import { Builder, builder } from '@builder.io/react';
import { getAsyncProps } from '@builder.io/utils';

export default function MyPage(props) {
  return <BuilderComponent model="page" content={props.content} />
}

export async function getStaticProps(context) {
  const content = await builder.get('page', { url: context.resolvedUrl }).promise();
  
  await getAsyncProps(content, {
    async Products(props) {
      return {
        data: await fetch(`${apiRoot}/products?cat=${props.category}`).then(res => res.json())
      }
    }
  })

  return { props: { content } }
}

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

import { Builder, withChildren } from '@builder.io/react';

export const Hero = props =>
  <div className={heroStyles}>{div}</div>

const HeroWithBuilderChildren = withChildren(Hero)

Builder.registerElement(HeroWithBuilderChildren, {
  name: 'Hero',
  // Adding defaults is important for easy usability
  defaultChildren: [
    { 
      '@type': '@builder.io/sdk:Element',
      component: { name: 'Text', options: { text: 'I am child text block!' } }
    }
  ]
})

If you want to be fancy and only allow certain types of children, you can do this with childRequirements like in this example

  childRequirements: {
    message: 'You can only put Buttons, Text, or Headings in a Hero',
    query: {
      'component.name': { $in: ['Button', 'Text', 'Heading'] },
    },
  }

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!

noWrap

By default Builder wraps your components in a dom element (by default a div but 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

import { TextField } from '@material-ui/core'

export const BuilderTextField = props => (
  // Important! Builder.io must add a couple classes and attributes via props.attributes
  // Important! If you add your own classes do it after ...props.attributes 
  <TextField 
    variant={props.variant} 
    {...props.attributes} 
    className={`my-class ${props.attributes.className}`}
   />
)

Builder.registerComponent(BuilderTextField, {
  name: 'TextField',
  noWrap: true, // Important!
  inputs: [{ name: 'variant', type: 'string' }]
})

Input type examples:

string: any text, usually shorter in length and unformatted

alias: text

  {
    name: 'buttonText',
    type: 'string',
    defaultValue: 'Click',
  }

number: an input field expected to take a number such as an amount

  {
    name: 'amount',
    type: 'number',
    defaultValue: 20,
  }

boolean: an input field taking true or false

  {
    name: 'darkMode',
    type: 'boolean',
    defaultValue: true,
  }

longText: same as string type but with a multiline text field editor. (if formatted, use richText)

  {
    name: 'description',
    type: 'longText',
    defaultValue: 'Builder is the first and only headless CMS with a powerful 
    drag-and-drop visual editor that lets you build, 
    optimize, and measure digital experiences with speed and flexibility'
  }

richText: Displays a rich text editor and provides the value as html

alias: html

  {
    name: 'description',
    type: 'richText',
    defaultValue: '<b>This text is bold</b>'
  }

file: Uploads a file and provides the value as a url string. See allowedFileTypes for additional details.

  { 
    name: 'image',
    type: 'file', 
    allowedFileTypes: ['jpeg', 'png'] 
  }

color: provides a color value (hex or rgb) to a component

 {
    name: 'backgroundColor',
    type: 'color',
    defaultValue: '#fafafafa',
  }

date: any format that the date constructor for Javascript takes

  {
    name: 'event',
    type: 'date',
    defaultValue: 'December 17, 1995 03:24:00', 
  }

email: create an email value for a component

  {
    name: 'signup',
    type: 'email',
    defaultValue: 'noreply@email.com'
  }

object: a set of specific names and values

*note: you will get errors if no defaultValue is set for objects 
  {
      name: 'Carousel',
      type: 'object',
      defaultValue: {
         variant: 'primary'
      },
      subFields: [
        {
          name: 'text',
          type: 'string',
          required: true,
        },
        {
          name: 'url',
          type: 'url',
          required: true,
        },
        {
          name: 'variant',
          type: 'string',
          defaultValue: 'primary',
          enum: ['primary', 'info', 'dark', 'light', 'warning'],
        },
      ],
    }

list:ο»Ώ list of items

alias: array

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

{
      name: 'reviews',
      type: 'list',
      defaultValue: [ 
            { reviewText: 'hello' 
     }],
      subFields: [
	{
          name: 'reviewText',
          type: 'string',
          defaultValue: '"You guys are 
          the best"',
        },
        {
          name: 'reviewAuthor',
          type: 'string',
          defaultValue: 'Jane Smith',
        },
        {
          name: 'image',
          type: 'file',
          allowedFileTypes: ['jpeg', 'jpg', 'png', 'svg'],
          required: true,
          defaultValue:
         'https://cdn.builder.io/api/v1/image/assets%2Fpwgjf0RoYWbdnJSbpBAjXNRMe9F2%2Ffb27a7c790324294af8be1c35fe30f4d',
        },
      ],
    }

Components-only mode

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!

Up next

Components-only mode
Was this article helpful?