Component definition

Overview

When registering a custom component, the component and definition field need to be defined.

export const ButtonComponentRegistration = {
  component: Button,
  definition: {
    /* Component definition */
  },
};
defineComponents([ButtonComponentRegistration]);

The definition object contains both required and optional fields. For example, each component definition must have a unique ID. Some IDs are already used by Contentful for the out-of-the-box components which can be found in the Experiences repository.

Component definition fields

id

Description: Unique arbitrary string. Is used to identify the component that has to render at a certain place on a page. Allowed characters: alphanumeric, -, and _. Max length = 32 characters.

Required: true

Value type: string

Default value: undefined

name

Description: User-friendly name of the registered component, which will be rendered to the user within the Experiences canvas.

Required: true

Value type: string

Default value: undefined

category

Description: Arbitrary string. All component definitions that have the same category value are grouped together within the Experiences canvas.

Required: false

Value type: string

Default value: undefined

children

Description: Indicates whether such component supports nesting. If true - such component can be used as a container and other components can be nested within as children elements.

Required: false

Value type: boolean

Default value: false

thumbnailUrl

Description: The image provided is rendered within the registered component card in the Experiences canvas.

Required: false

Value type: string

Default value: undefined

tooltip

Description: The tooltip option adds an informational tooltip to the Component card element in the Components sidebar. This tooltip is displayed as a clickable icon. When using this option, a description is required, and an optional imageUrl can also be provided.

Required: false

Value type: object

Default value: undefined

Variable definition

builtInStyles

Description: For each value provided, the Experiences canvas UI renders a dedicated control for selecting a respective style value. The style value is then provided into the registered component as a className prop.

Possible values:

['cfHorizontalAlignment', 'cfVerticalAlignment', 'cfMargin', 'cfPadding',
  'cfBackgroundColor', 'cfWidth', 'cfMaxWidth', 'cfHeight', 'cfFlexDirection',
  'cfFlexWrap', 'cfBorder', 'cfGap', 'cfImageAsset', 'cfImageOptions',
  'cfBackgroundImageUrl', 'cfBackgroundImageOptions', 'cfFontSize',
  'cfFontWeight', 'cfLineHeight', 'cfLetterSpacing', 'cfTextColor',
  'cfTextAlign', 'cfTextTransform', 'cfTextBold', 'cfTextItalic', 'cfTextUnderline']

Required: false

Value type: Array<string>

Default value: ['cfMargin']

Example: Built-in styles

variables

Description: Key-value pair, where key is the prop name (defined by component implementation) and value is the variable definition. Allowed characters: alphanumeric, - and _. Max length = 32 characters.

Required: true

Value type: object - possible values described below

Default value: undefined

Variable definition fields

type

Description: Data type of the prop, expected by a component. Possible values: Text, RichText, Number, Date, Boolean, Location, Media, Link, Array, Object, Hyperlink.

Required: true

Value type: string

Default value: undefined

validations

Description: Optionally provide rules to enforce certain data formats for a variable.

Required: false

Default value: undefined

Type definition:

type BindingSourceType = 'entry' | 'asset' | 'experience' | 'manual';
{
  [variableName: string]: {
    ...
    in?: Array<{ value: string; displayName: string }>;
    bindingSourceType?: BindingSourceType[];
  }
}

Properties:

      in: allows pre-defined values to be displayed in Experiences <select> control. Only applies to style variables.

      bindingSourceType: allows list of content sources to be bound to that variable. Possible values: ["entry", "asset", "experience", "manual"].

Example:

import type { ComponentDefinition } from '@contentful/experiences-core/types';
const HeadingComponentDefinition: ComponentDefinition = {
  ...
  variables: {
    headingHtmlTag: {
      validations: {
      ...
      in: [
        { value: 'h1', displayName: 'H1' },
        { value: 'h2', displayName: 'H2' },
        ...
        { value: 'h6', displayName: 'H6' },
      ]
    },
    bannerImage: {
      validations: {
        // allow binding to an entry, asset, but
        // disallow binding to 'experience' or 'manual'
        bindingSourceType: ['entry', 'asset',],
      }
    }
  },
}

description

Description: Description of the variable. Can be used to provide a prompt on the variable’s purpose that is rendered as part of the control in the Experiences UI.

Required: false

Value type: string

Default value: undefined

displayName

Description: User-facing name of the component that is rendered in the Experiences UI.

Required: false

Value type: string

Default value: undefined

defaultValue

Description: A value used by default if no value for a prop has been selected. The value type must match the expected value type by the component. Eg: boolean if component prop expects boolean.

Required: false

Value type: any

Default value: undefined

group

Description: Marks a prop as a design variable if style is provided. Design variables get hardcoded in an experience and do not allow binding (getting a value by a reference from an existing entry or asset). For more information, see Variable types in Experiences.

Possible values: style, content

Required: false

Value type: string

Default value: content