Made in Builder.io

Announcing Visual Copilot - Figma to live in half the time

Builder.io logo
Talk to Us
Platform
Developers
Talk to Us

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

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

With the registerComponent() function, you can define and register custom components for the Visual Editor with tailored solutions by defining properties, behavior, and appearance of your components.

To get the most out of this document, you should be familiar with Registering Custom Components.

Type: string

Assign a unique name to identify, reference, and register the component.

Builder.registerComponent('MyButton', {
  name: 'MyButton',
  // Other properties...
});

To override a built-in component with your custom component, you can use the same name as the built-in component. For example, to replace the built-in Text component, you can register your component with the name Text:

Builder.registerComponent('Text', {
  // Overrides built-in Text component
  name: 'Text',
  // Other properties...
});

Type: boolean

Set to true if your component can accept children. Use in combination with withChildren(YourComponent); that is, only use canHaveChildren when a component will have children.

Builder.registerComponent(HeroWithBuilderChildren, {
  name: 'Hero',
  canHaveChildren: true, // Can have child components
  ...
});

See also: GitHub example

Tip: Builder's Gen 2 SDKs don't requirewithChildren(). For more information on the SDKs, visit SDK Comparision.

Type: object

Specify restrictions on the direct children of a component. Use to define the rules that the children must match in order to be considered valid.

NameTypeDescription

component?

string

Optional. Specifies a component name. This property provides a direct way to enforce that the children must be of a specific component type.

message

string

Message to show when the child requirements are not met. Use to provide information or instructions to the user about the expected child components. For example, "Children of 'Columns' must be a 'Column'".

query?

any

Optional. Use for more advanced requirements by specifying a MongoDB-style query using the sift.js library. Use to define complex conditions that the children objects must match. You can use various operators, such as $in, $eq, $ne, $gt, $lt, to create the desired conditions.

Example of childRequirements with a query:

childRequirements: {
  query: {
    // The child of this element must be 
    // a 'Button' or 'Text' component
    'component.name': { $in: ['Button', 'Text'] }
  }
}

Type: BuilderElement[]

Use to specify the default child elements for a component. It is an array that contains BuilderElement objects, which represent the child elements within the component.

Builder.registerComponent(HeroWithBuilderChildren, {
  name: 'Hero',
  defaultChildren: [
    { 
      '@type': '@builder.io/sdk:Element',
       component: { name: 'Text', options: { text: 'I am child text block!' } }
    }
  ]
});

Type: object

Specify default styles for an element or component when it is dropped into the Builder.io editor.

Accepts an object where each key represents a breakpoint or screen size, and the corresponding value is a set of CSS styles to be applied at that breakpoint.

Tip: defaultStyles is an alias for defaults.responsiveStyles.large and offers a way for developers to conveniently default styles for all default sizes. For specifying responsive styles, use the defaults property.

Builder.registerComponent(SaleBanner, {
  name: 'Sale Banner',
  defaultStyles: {
    backgroundColor: 'red',
    color: 'white',
    fontSize: '24px'
  }
});

Type: Partial<BuilderElement>

Provide default options for the block when it is created. When a new instance of the block is created, these default options will be merged with any user-defined options, providing initial values for the block's properties.

For instance, to define responsive styles, use defaults.responsiveStyles:

Builder.registerComponent(SaleBanner, {
  name: 'Sale Banner',
  defaults: {
    responsiveStyles: {
      // Index signature with dynamic keys and string values
      large: {
        backgroundColor: 'red',
        color: 'white',
        fontSize: '24px'
      },
      small: {
        backgroundColor: 'green',
        color: 'black',
        fontSize: '16px'
      },
    }
  }
});

Type: string

Provide a link to a documentation page for the component. It is a string that represents the URL of the documentation page. This is helpful for users who want to learn more about the component's features, usage, or customization options.

Builder.registerComponent(InfoCallOut, {
  name: 'Info Call Out',
  docsLink: 'https://www.builder.io/c/docs/developers',
  // Other properties...
});

Type: boolean

Hide your component in editor, useful for gradually deprecating and Versioning Custom Components.

Builder.registerComponent(Heading, { 
  name: 'Heading', 
  hideFromInsertMenu: true, // <-- don't show in Insert tab
  ...
})

Type: string

Link to an image to be used as an icon for this component in Builder's Visual Editor.

Builder.registerComponent(Hero, {
  name: 'Hero',
  // replace with your actual asset URL
  image: 'https://cdn.builder.io/hero-image.jpg',
  // Other properties...
});

Type: Input[]

Represents the input schema for the component which is an array of Input objects that define the options in the user interface (UI) to configure the component's properties or behavior.

Each input object specifies properties, for example:

Builder.registerComponent('MyComponent', {
  name: 'MyComponent',
  inputs: [
    {
      name: 'text',
      type: 'text',
      label: 'Text Input',
      defaultValue: 'Hello, Builder!',
      required: true
    }
  ],
  // Other properties...
});

Type: string[]

Use to restrict the usage of a component to specific models. By providing a list of model names, the component will only be available for those models. If models is not specified, the component is available for all models.

In the following example, MyComponent is available only for the Page and Hero models.

Builder.registerComponent('MyComponent', {
  name: 'MyComponent',
  models: ['Page', 'Hero'],
  // Other properties...
});

Type: boolean

Assign a unique name to identify, reference, and register the component.

Builder.registerComponent('FormInputComponent', {
  name: 'FormInputComponent',
  noWrap: true
  // Other properties...
});

Make sure to use {...props.attributes} so the component receives the necessary attributes to function properly.

class FormInputComponent extends React.Component<FormInputProps> {
  render() {
    return (
      <input
        // other attributes
        {...this.props.attributes}
      />
    );
  }
}
// See GitHub for full example

This snippet is an excerpt from the full FormInputComponent on Github.

Type: boolean

Override the behavior of a built-in component. Any special behavior or functionality provided by the default button component, such as virtual options or custom editors, are skipped.

Builder.registerComponent('Button', {
  name: 'Button',
  override: true
  // Other properties...
});

Type: Permission[]

Specify the availability of the component dependent on permissions.

Possible Permission values are read, publish, editCode, editDesigns, admin, and create.

Builder.registerComponent('Button', {
  name: 'Button',
  requiredPermissions: ['editDesigns'],
  // Other properties...
});

For more information, see Roles and Permissions by Space.

Type: object

Specify restrictions on the parent component that must be met in order for the current component to be valid. Use to define requirements for the parent component's properties or type.

// example parent component
Builder.registerComponent('ProductBox', {
  name: 'Product Box',
  // Other properties...
});
// component that requiresParent
Builder.registerComponent('AddToCartButton', {
  name: 'Add to Cart Button',
  requiresParent: {
    component: 'Product Box',
    message: "'Add to Cart' buttons must be within a 'Product Box'",
  },
  // Other properties...
});

The available requiresParent options are:

  • message: A string that represents the message to be displayed when the parent requirement is not met.
  • component (optional): Specify that the parent component must be a particular component name.
  • query (optional): Specify a MongoDB-style query using the sift.js library. This query defines the conditions that at least one parent in the hierarchy should match. The following example uses the component.name field to check if the parent is either a Product box or a Collection component.
query: {
   // Thils element must be somewhere inside 
   // either a 'Product box' or 'Collection' component
  'component.name': { $in: ['Product Box', 'Collection'] }
}

Type: string

Provide a screenshot that is displayed when a user hovers over the component in the Visual Editor.

Builder.registerComponent(MyComponent, {
  name: 'MyComponent',
  // replace with your actual asset URL
  screenshot: 'https://cdn.builder.io/my-component-screenshot.png',
  // other component properties...
});

See also the Image API and Builder's CDN.

Type: string

Use to specify a custom tag name for your custom web components. In this example, you could use <my-custom-component>.

Builder.registerComponent(MyCustomComponent, {
  name: 'MyCustomComponent',
  tag: 'my-custom-component',
  // other component properties...
});

The tag property is specifically for custom web components and is not applicable to other types of components.

Working with custom components opens up endless opportunities. For more on custom components, read:

Was this article helpful?

Product

Visual CMS

Theme Studio for Shopify

Sign up

Login

Featured Integrations

React

Angular

Next.js

Gatsby

Get In Touch

Chat With Us

Twitter

Linkedin

Careers

© 2020 Builder.io, Inc.

Security

Privacy Policy

Terms of Service

Newsletter

Get the latest from Builder.io

By submitting, you agree to our Privacy Policy