registerComponent() options

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.

Prerequisites

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

Required: name property

name

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...
});

Optional properties

canHaveChildren

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
  ...
});

childRequirements

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.

Name	Type	Description
`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'] } } }`

defaultChildren

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!' } }
    }
  ]
});

defaultStyles

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'
  }
});

defaults

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'
      },
    }
  }
});

docsLink

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
  ...
})

image

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...
});

inputs

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...
});

models

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...
});

noWrap

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.

override

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...
});

requiredPermissions

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.

requiresParent

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'] }
}

screenshot

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.

tag

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.

What's next

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

Was this article helpful?