Child blocks in custom components

When you want your custom component to accept other blocks, configure your component with children. The following video demonstrates a custom tabs component that accepts Builder blocks as content. Each tab receives a unique block that the user drags and drops in.

Prerequisites

To get the most out of this tutorial, you should have the following:

An app you've integrated with Builder
Familiarity with using custom components

Basic child blocks example

The most fundamental use case is a basic container that accepts draggable content. This section demonstrates a hero component that users can drag and drop other blocks into.

Diagram of a custom component with a slot in it where you can add Builder blocks. There's a note with an arrow that says "Drop Builder blocks here".

Framework

Meta-Framework

SDK Generation

Register the component with Builder, specifying that it can accept children:

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

// Define the component
const CustomHero = (props: PropsWithChildren) => {
  return (
    <>
      <div>This is your component's text</div>
      {props.children}
    </>
  );
};

  // IMPORTANT: withChildren is required to enable child block functionality
  const HeroWithBuilderChildren = withChildren(CustomHero);

// Register with Builder
Builder.registerComponent(HeroWithBuilderChildren, {
  name: 'CustomHero',
  inputs: [],
  canHaveChildren: true,
  defaultChildren: [
    {
      '@type': '@builder.io/sdk:Element',
      component: {
        name: 'Text',
        options: {
          text: 'This is Builder text',
        },
      },
    },
  ],
});

export default CustomHero;

Register your component with Builder to define how it appears and behaves in the Visual Editor. The registration configuration:

Sets the component's name and input fields
Enables child blocks with canHaveChildren
Provides default content with defaultChildren
Makes the component available in the Visual Editor's Insert tab

Setting child requirements

To allow only certain types of children, configure childRequirements:

Builder.registerComponent(..., {
  name: 'Your-custom-component',
  ...
  childRequirements: {
    message: 'You can only put Buttons, Text, or Images in a Hero',
    query: {
      'component.name': { $in: ['Button', 'Text', 'Image'] },
    },
  }
})

Place the childRequirements object inside registerComponent() after defaultChildren. With this configuration, the custom component only accepts Button, Text, or Image blocks.

To test your component, visit any Page in your web browser that renders this component.

The following video demonstrates adding children to custom components using a basic hero banner.

Single editable regions work well for basic components. However, more complex layouts often require multiple distinct areas for content. The next example covers how to create a two-column layout with separate editable regions.

Multiple named editable regions

A common need is having multiple distinct areas within a custom component where users can add content. This section covers an example shows how to create a two-column layout where each column is a separate editable region.

Diagram of a custom component with two slots in it where you can add Builder blocks. There's a note with an arrow that says "Drop Builder blocks here".

Two-column layout example

Framework

Meta-Framework

SDK Generation

This example shows how to create a layout component with two distinct editable regions. Users can add different content to each column independently in the Visual Editor.

The component uses BuilderBlocks for each column, which requires these props:

parentElementId to identify which Builder block owns the content
dataPath to store each column's content in the correct location
blocks to manage the actual content for each column

The component registration defines two editable regions using uiBlocks:

A left column that can contain any Builder blocks
A right column that can contain any Builder blocks

Users can drag and drop different Builder components into each column independently, creating flexible two-column layouts.

import { 
  Builder, 
  BuilderBlocks, 
  type BuilderElement 
} from '@builder.io/react';

// Define the component
type BuilderProps = {
  column1: BuilderElement[];
  column2: BuilderElement[];
  builderBlock: BuilderElement;
};

const CustomColumns = (props: BuilderProps) => {
  return (
    <>
      <BuilderBlocks
        parentElementId={props.builderBlock.id}
        dataPath={`column1.blocks`}
        blocks={props.column1}
      />
      <BuilderBlocks
        parentElementId={props.builderBlock.id}
        dataPath={`column2.blocks`}
        blocks={props.column2}
      />
    </>
  );
};

// Register with Builder
Builder.registerComponent(CustomColumns, {
  name: 'MyColumns',
  inputs: [
    {
      name: 'column1',
      type: 'uiBlocks',
      defaultValue: {
        blocks: [],
      },
    },
    {
      name: 'column2',
      type: 'uiBlocks',
      defaultValue: {
        blocks: [],
      },
    },
  ],
});

export default CustomColumns;

Dynamic slots (regions)

For more complex use cases, you might need multiple editable regions or slots that can be added dynamically. This tabs example demonstrates how to create a component where users can add new tabs, each with its own editable content area.

Dynamic tabs example

Framework

Meta-Framework

SDK Generation

This example shows how to create a tabs component where users can add new tabs dynamically and customize the content of each tab. The component:

Creates a tab navigation interface where users can switch between tabs
Provides an editable region within each tab using BuilderBlocks
Uses parentElementId to connect the blocks to the parent component
Uses dataPath to specify where the tab's content is stored
Uses blocks to contain the actual content for the active tab

The component registration defines an array input for the tabs, where each tab includes:

A name field for the tab label
A blocks field for the tab's content, using the uiBlocks type

Users can add new tabs and customize their content directly in the Visual Editor.

import { 
  Builder, 
  BuilderBlocks, 
  type BuilderElement 
} from '@builder.io/react';
import { useState } from 'react';

// Define the component
type TabProps = {
  tabList: { tabName: string; blocks: React.ReactNode[] }[];
  builderBlock: BuilderElement;
};

const CustomTabs = ({ tabList, builderBlock }: TabProps) => {
  const [activeTab, setActiveTab] = useState(0);

  if (!tabList?.length) return null;

  return (
    <>
      <div className="tab-buttons">
        {tabList.map((tab, index) => (
          <button
            key={index}
            className={`tab-button ${activeTab === index ? 'active' : ''}`}
            onClick={() => setActiveTab(index)}
          >
            {tab.tabName}
          </button>
        ))}
      </div>

      <BuilderBlocks
        parentElementId={builderBlock?.id}
        dataPath={`tabList.${activeTab}.blocks`}
        blocks={tabList[activeTab].blocks}
      />
    </>
  );
};

// Register with Builder
Builder.registerComponent(CustomTabs, {
  name: 'TabFields',
  inputs: [
    {
      name: 'tabList',
      type: 'array',
      defaultValue: [],
      subFields: [
        {
          name: 'tabName',
          type: 'string',
        },
        {
          name: 'blocks',
          type: 'uiBlocks',
          hideFromUI: true,
          defaultValue: [],
        },
      ],
    },
  ],
});

export default CustomTabs;

What's next

To customize your components even further, leverage Builder's Input Types.

For more details on child-related options when working with child components, visit the canHaveChildren, childRequirements, and defaultChildren sections of the registerComponent() documentation.

For more examples of custom components with multiple sets of children, visit:

Child blocks in custom components

Prerequisites

Basic child blocks example

Multiple named editable regions

Two-column layout example

Dynamic slots (regions)

Dynamic tabs example

What's next

Get the latest from Builder

Platform

Developer Resources

Frameworks

Resources

Popular Guides

Company