Register custom components

Table of contents

• What are custom components?
• Component requirements
• Component registration
• Enable tooltips for registered components
• Component wrapper
  • Disabling the wrapping container
  • Changing the wrapping container tag
• Built-in components
  • Disabling all built-in components
  • Enabling specific built-in components

What are custom components?

You can import your own design system components into Experiences to create on-brand digital experiences.

After the setup in Contentful is completed, once you open the experience entry in the Contentful web app, you can see the canvas view with your page rendered in the iframe.

In this step, let’s register some custom components to further use them in Experiences.

Registering a component consists of the following steps:

• Importing a component from the source package or folder.
• Writing a component definition - a JSON object that Contentful uses to pass necessary properties to the component.
• Passing the component definition to the SDK via a provided function.

Component requirements

In order to fully support Experiences, your registered components must match the following requirements:

• Handle className property, to enable Experiences to apply styles to the instance of a registered component
• Handle onMouseDown, onClick props. Experiences prevents native click events (to avoid unnecessary redirects)
• Handle the following props which enable canvas interactions to function properly:
  • data-cf-node-id
  • data-cf-node-block-id
  • data-cf-node-block-type

As we develop this product, the list of required props might change, so it is recommended to register components that support props spreading as in the example below (experiencesProps):

import React, { ReactNode } from 'react';

type AnchorProps = {
  href: string;
  rel?: string;
  target?: string;
  chilren: ReactNode
};

export const Anchor = ({ href, rel, target = '_self', children, ...experiencesProps }: AnchorProps) => {
  return (
    <a href={href} rel={rel} target={target} {...experiencesProps}>
       {children}
    </a>
  );
}

Component registration

To register a custom component, import the defineComponents function directly from our side SDK:

import { defineComponents } from '@contentful/experiences-sdk-react';

import { Component1, Component2 } from '/components';
import { component1Definition, component2Definition } from '/componentDefinitions';

defineComponents([
  {
    component: Component1,
    definition: component1Definition
  },
  {
    component: Component2,
    definition: component2Definition
  }
]);

Enable tooltips for registered components

Notice how in the ComponentDefinition type that there's an optional tooltip field defined as

  tooltip?: {
    imageUrl?: string;
    description: string;
  };

When defining a tooltip, only the description is required. However, you are also able to provide your editors with a visual description of the registered component along with the description. With these options, you are enabled to customize a powerful educational experience for your users.

Defining just the description outputs a tooltip like:

Providing an image URL along with a description outputs a tooltip like:

Component wrapper

Components that are registered will be encapsulated within a <div> element, serving as a wrapping container for the component.

All the styles generated from Experiences will be applied to the wrapping container instead of the component itself. This will make it so the additional styles don't interfere with your component's styles.

Disabling the wrapping container

The wrapping container can be disabled by setting the wrapComponent option to false in the component registration.

import { defineComponents } from '@contentful/experiences-sdk-react';

import { Component } from '/components';
import { componentDefinition } from '/componentDefinitions';

defineComponents([
  {
    component: Component,
    definition: componentDefinition,
    options: { wrapComponent: false }
  }
]);

Changing the wrapping container tag

The wrapping container tag can be changed by setting the wrapContainerTag option in the component registration.

import { defineComponents } from '@contentful/experiences-sdk-react';

import { Component } from '/components';
import { componentDefinition } from '/componentDefinitions';

defineComponents([
  {
    component: Component,
    definition: componentDefinition,
    options: { wrapContainerTag: 'span' }
  }
]);

Built-in components

Contentful provides some built-in basic components such as Heading, Text, Rich Text, Image, and Button. These basic components are enabled by default. If desired, you can disable these components when defining your custom components using the defineComponents function.

Disabling all built-in components

To disable all built-in components, pass an options object to defineComponents with enabledBuiltInComponents set to an empty array.

defineComponents(
  [
    /* custom component definitions */
  ],
  {
    enabledBuiltInComponents: [],
  }
);

Enabling specific built-in components

You can also choose to enable only specific built-in components. To do this, pass an array of the IDs of the components you want to enable to enabledBuiltInComponents.

In the following example, all built-in components except the Image component are enabled:

import { CONTENTFUL_COMPONENTS } from '@contentful/experiences-sdk-react';

defineComponents(
  [
    /* custom component definitions */
  ],
  {
    enabledBuiltInComponents: [
      CONTENTFUL_COMPONENTS.button.id,
      CONTENTFUL_COMPONENTS.heading.id,
      CONTENTFUL_COMPONENTS.richText.id,
      CONTENTFUL_COMPONENTS.text.id,
    ],
  }
);