Implementing nested components with custom components

Overview

Complex user experiences often require nested components such as carousels, tabs, or accordions. These components typically consist of a wrapper component that accepts arbitrary children and decides where and how to render them, along with item components that provide the content for each slot.

This guide demonstrates how to implement these nested component patterns using Contentful Studio custom components via children: true, enabling editors to create rich, interactive experiences while maintaining full control over the component structure and facilitating full editability in Studio.

Architecture overview

The solution follows a parent-child component pattern where:

  • Parent components (Carousel, Tabs) accept children and control the overall structure
  • Child components (CarouselSlide, TabsItem) provide content for each slot
  • Communication happens through React’s children API and component props
  • Editor experience is optimized using the built-in interactive vs. design mode toggles

Key components

  • Wrapper components with children: true that accept arbitrary child components
  • Item components that provide content and metadata for each slot
  • Interactive controls for editors to switch between design and preview
  • Type-safe communication between parent and child components

Data flow

  1. Editor experience:
    1. Editor adds parent component (e.g., Carousel)
    2. Editor adds child components (e.g., CarouselSlide) inside the parent
    3. Parent component reads child properties and renders accordingly
  2. End-user experience:
    1. Components render with full interactivity
    2. User can interact with carousels, tabs, etc.
    3. Content updates dynamically based on user interactions

Prerequisites

Before starting this exemplary implementation, ensure you have…

  • A Next.js project with App Router
  • Contentful Experiences SDK installed (@contentful/experiences-sdk-react)
  • A UI library like Ant Design for complex components
  • Basic understanding of React children patterns
  • TypeScript for type safety
The underlying concept and implementation solution will work with any tech stack, so this stack is just exemplary for demonstration purposes.

Setting up the project structure

The example implementation follows this directory structure…

src/
├── components/
│   ├── CarouselComponentRegistration.tsx
│   ├── CarouselSlideComponentRegistration.tsx
│   ├── TabsComponentRegistration.tsx
│   ├── types.ts
│   └── *.module.css
├── utils/
│   ├── types.ts
│   └── store.ts
└── studio-config.ts

The carousel implementation consists of two components: a CarouselComponent that wraps the carousel functionality and a CarouselSlideComponent that represents individual slides.

The carousel component accepts children and provides carousel functionality with autoplay support. The editor experience also is tailored to prevent the carousel from sliding when editing content in edit mode while keeping it interactive both in interactive mode as well as end-users.

1// src/components/CarouselComponentRegistration.tsx
2import React from 'react';
3import { ComponentRegistration } from '@contentful/experiences-sdk-react';
4import clsx from 'clsx';
5import { CustomComponentProps } from './types';
6import { Carousel } from 'antd';
7
8import styles from './CarouselComponentRegistration.module.css';
9
10type CarouselComponentProps = CustomComponentProps<{
11  children: React.ReactNode;
12  autoplay: string;
13}>;
14
15export const CarouselComponentRegistration: ComponentRegistration = {
16  component: ({
17    className,
18    children,
19    autoplay,
20    isEditorMode,
21    // https://www.contentful.com/developers/docs/experiences/custom-components/#component-requirements
22    ...rest
23  }: CarouselComponentProps) => {
24    return (
25      <div className={clsx(className, styles.carousel)} {...rest}>
26        <Carousel
27          autoplay={Boolean(autoplay && !isEditorMode)}
28          autoplaySpeed={Number(autoplay)}
29          arrows
30        >
31          {children}
32        </Carousel>
33      </div>
34    );
35  },
36  options: {
37    enableEditorProperties: {
38      isEditorMode: true,
39    },
40    wrapComponent: false,
41  },
42  definition: {
43    id: 'custom-carousel',
44    name: 'Carousel',
45    category: 'Structure',
46    children: true,
47    variables: {
48      autoplay: {
49        displayName: 'Autoplay Delay',
50        type: 'Number',
51        group: 'content',
52      },
53    },
54  },
55};

The carousel slide component represents individual slides within the carousel.

1// src/components/CarouselSlideComponentRegistration.tsx
2import React from 'react';
3import { ComponentRegistration } from '@contentful/experiences-sdk-react';
4import clsx from 'clsx';
5import { CustomComponentProps } from './types';
6
7import styles from './CarouselSlideComponentRegistration.module.css';
8
9type CarouselSlideComponentProps = CustomComponentProps<{
10  children: React.ReactNode;
11  title: string;
12}>;
13
14export const CarouselSlideComponentRegistration: ComponentRegistration = {
15  component: ({
16    className,
17    children,
18    title,
19    // https://www.contentful.com/developers/docs/experiences/custom-components/#component-requirements
20    ...rest
21  }: CarouselSlideComponentProps) => {
22    return (
23      <div
24        className={clsx(className, styles.carouselSlide)}
25        title={title}
26        {...rest}
27      >
28        {children}
29      </div>
30    );
31  },
32  options: {
33    wrapComponent: false,
34  },
35  definition: {
36    id: 'custom-carousel-slide',
37    name: 'Carousel Slide',
38    category: 'Structure',
39    children: true,
40    variables: {
41      title: {
42        displayName: 'Title',
43        type: 'Text',
44        group: 'content',
45      },
46    },
47  },
48};

Creating the tabs components

The tabs implementation demonstrates more complex parent-child communication, where the parent component needs to extract information from its children to build the tab navigation.

Utility Types and Functions

Be aware that interacting with the entity store like shown in the following exemplary implementation is a NOT OFFICIALLY SUPPORTED strategy. We’re exploring having a standalone SDK method for this in a future version, so use/adapt the subsequent example implementation at your own risk.

First, we need utility functions to handle bound and unbound values from the Experiences SDK:

1// src/utils/types.ts
2import { type EntityStore } from '@contentful/experiences-core';
3import {
4  BoundValue,
5  ComponentTreeNode,
6  UnboundValue,
7} from '@contentful/experiences-validators';
8import { isValidElement, ReactElement } from 'react';
9
10export type ValueOfRecord<R> = R extends Record<string, infer T> ? T : never;
11
12export type Variable = ValueOfRecord<ComponentTreeNode['variables']>;
13
14export type CompositionNode = {
15  node: ComponentTreeNode;
16  locale: string;
17  entityStore: EntityStore;
18  wrappingPatternIds: never;
19  wrappingParameters: never;
20  patternRootNodeIdsChain: string;
21};
22
23export const isValidCompositionNode = (
24  element: unknown
25): element is ReactElement<CompositionNode> => {
26  return Boolean(
27    isValidElement(element) &&
28      element.props &&
29      typeof element.props === 'object' &&
30      'node' in element.props
31  );
32};
33
34export const isUnboundValue = (
35  variable: Variable
36): variable is UnboundValue => {
37  return variable.type === 'UnboundValue';
38};
39
40export const isBoundValue = (variable: Variable): variable is BoundValue => {
41  return variable.type === 'BoundValue';
42};
1// src/utils/store.ts
2import { type EntityStore } from '@contentful/experiences-core';
3import { UnresolvedLink } from 'contentful';
4
5export const resolveUnboundValue = (
6  entityStore: EntityStore,
7  mappingKey: string,
8  defaultValue: string
9) => {
10  return entityStore.unboundValues[mappingKey]?.value ?? defaultValue;
11};
12
13export const resolveBoundValue = (
14  entityStore: EntityStore,
15  path: string,
16  defaultValue: string
17) => {
18  const [, uuid, , field] = path.split('/');
19  const boundEntityLink = entityStore.dataSource[uuid] as UnresolvedLink<
20    'Entry' | 'Asset'
21  >;
22  const resolvedEntity = entityStore.getEntryById(boundEntityLink.sys.id);
23  return resolvedEntity?.fields[field] ?? defaultValue;
24};

Tabs Component

The tabs component processes its children to extract tab labels (= the label attribute of the child custom component) and creates the tab navigation:

1// src/components/TabsComponentRegistration.tsx
2import React, { ReactElement } from 'react';
3import { ComponentRegistration } from '@contentful/experiences-sdk-react';
4import clsx from 'clsx';
5import { CustomComponentProps } from './types';
6import { Tabs } from 'antd';
7import {
8  CompositionNode,
9  isBoundValue,
10  isUnboundValue,
11  isValidCompositionNode,
12} from '../../../utils/types';
13import { resolveBoundValue, resolveUnboundValue } from '../../../utils/store';
14
15import styles from './TabsComponentRegistration.module.css';
16
17type TabsComponentProps = CustomComponentProps<{
18  children: React.ReactNode;
19  active: number;
20}>;
21
22type TabsItemComponentProps = CustomComponentProps<{
23  children: React.ReactNode;
24  label: string;
25}>;
26
27const isValidTabItem = (
28  element: unknown
29): element is ReactElement<CompositionNode> => {
30  return (
31    isValidCompositionNode(element) &&
32    element.props.node.definitionId === 'custom-tabs-item'
33  );
34};
35
36export const TabsComponentRegistration: ComponentRegistration = {
37  component: ({
38    className,
39    children,
40    active,
41    // https://www.contentful.com/developers/docs/experiences/custom-components/#component-requirements
42    ...rest
43  }: TabsComponentProps) => {
44    const items = React.Children.map(children, (child, index) => {
45      const fallbackLabel = `Fallback ${index + 1}`;
46      const fallbackKey = `tab-fallback-${index + 1}`;
47
48      if (isValidTabItem(child)) {
49        return {
50          label: String(
51            isUnboundValue(child.props.node.variables.label)
52              ? resolveUnboundValue(
53                  child.props.entityStore,
54                  child.props.node.variables.label.key,
55                  fallbackLabel
56                )
57              : isBoundValue(child.props.node.variables.label)
58              ? resolveBoundValue(
59                  child.props.entityStore,
60                  child.props.node.variables.label.path,
61                  fallbackLabel
62                )
63              : fallbackLabel
64          ),
65          key: child.props.node.id ?? fallbackKey,
66          children: child,
67        };
68      }
69
70      return {
71        label: fallbackLabel,
72        key: fallbackKey,
73        children: child,
74      };
75    });
76
77    return (
78      <div className={clsx(className, styles.tabs)} {...rest}>
79        <Tabs items={items ?? []} defaultActiveKey={items?.[active - 1]?.key} />
80      </div>
81    );
82  },
83  options: {
84    wrapComponent: false,
85  },
86  definition: {
87    id: 'custom-tabs',
88    name: 'Tabs',
89    category: 'Structure',
90    children: true,
91    variables: {
92      active: {
93        displayName: 'Active',
94        type: 'Number',
95        group: 'content',
96      },
97    },
98  },
99};
100
101export const TabsItemComponentRegistration: ComponentRegistration = {
102  component: ({
103    className,
104    children,
105    // https://www.contentful.com/developers/docs/experiences/custom-components/#component-requirements
106    ...rest
107  }: TabsItemComponentProps) => {
108    return (
109      <div className={clsx(className, styles.tabsItem)} {...rest}>
110        {children}
111      </div>
112    );
113  },
114  options: {
115    wrapComponent: false,
116  },
117  definition: {
118    id: 'custom-tabs-item',
119    name: 'Tabs Item',
120    category: 'Structure',
121    children: true,
122    variables: {
123      label: {
124        displayName: 'Label',
125        type: 'Text',
126        group: 'content',
127      },
128    },
129  },
130};

Handling editor mode

One of the key considerations for nested components is handling the difference between editor and end-user experiences. Interactive components like carousels should behave differently in editor mode to prevent interference with the editing process.

Interactive vs. Design Mode

The carousel component demonstrates this by disabling autoplay when in editor mode:

1<Carousel
2  autoplay={Boolean(autoplay && !isEditorMode)}
3  autoplaySpeed={Number(autoplay)}
4  arrows
5>
6  {children}
7</Carousel>

This approach allows editors to:

  • Switch between interactive mode and design mode
  • Preview the component behavior without interference
  • Edit content without components auto-advancing
  • Test the full user experience when needed

Interactive mode vs. design mode toggle

Registering custom components

Register all your custom components with the Experiences SDK:

1// src/studio-config.ts
2import { defineComponents } from '@contentful/experiences-sdk-react';
3import { CarouselComponentRegistration } from './components/CarouselComponentRegistration';
4import { CarouselSlideComponentRegistration } from './components/CarouselSlideComponentRegistration';
5import {
6  TabsComponentRegistration,
7  TabsItemComponentRegistration,
8} from './components/TabsComponentRegistration';
9
10defineComponents([
11  CarouselComponentRegistration,
12  CarouselSlideComponentRegistration,
13  TabsComponentRegistration,
14  TabsItemComponentRegistration,
15]);

Best practices

Component Design

  • Keep components focused: Each component should have a single responsibility
  • Use consistent naming: Follow a clear naming convention for parent-child relationships
  • Provide fallbacks: Always provide fallback values for missing data
  • Handle edge cases: Consider what happens with empty or invalid children

Editor Experience

  • Disable interactivity in editor mode: Prevent auto-advancing carousels, auto-opening accordions, etc.
  • Provide visual feedback: Show component boundaries and relationships clearly
  • Support design mode: Allow editors to preview specific states (e.g., specific tab, specific slide)
  • Maintain parity: Keep editor experience close to end-user experience

Performance Considerations

  • Lazy loading: Consider lazy loading for complex nested components
  • Memoization: Use React.memo for expensive child components
  • Efficient re-renders: Minimize unnecessary re-renders in parent components

Type Safety

  • Strong typing: Use TypeScript for all component props and children
  • Runtime validation: Validate component structure at runtime
  • Error boundaries: Implement error boundaries for graceful failure handling

Conclusion

This implementation provides a robust foundation for creating complex nested components in Contentful Studio. The parent-child pattern enables rich, interactive experiences while maintaining editor-friendly workflows. The modular architecture makes it easy to extend and adapt for different use cases.

Key benefits of this approach

  • Flexibility: Support for arbitrary nesting and content
  • Editor experience: Intuitive editing with visual feedback
  • Type safety: Full TypeScript support for component communication
  • Performance: Optimized rendering and interaction handling
  • Maintainability: Clear separation of concerns and reusable patterns

For more advanced use cases, consider implementing additional features like:

  • Dynamic content: Support for content that changes based on user interactions
  • State management: Complex state handling for multi-step components
  • Accessibility: Enhanced accessibility features for screen readers
  • Analytics: Tracking component usage and user interactions