Component definition

Overview

A component definition is a Javascript object of the following required properties:

import type { ComponentDefinition } from '@contentful/experiences-sdk-react'

const componentDefinition: ComponentDefinition = {
  id: string;
  name: string;
  variables: {
    [variableName]: {
      type: 'Text' | 'RichText' | 'Number' | 'Date' | 'Boolean' | 'Location' | 'Media' | 'Link' | 'Array' | 'Object' | 'Hyperlink';
    },
  }
}

Such object must describe the component with the properties it supports and be unique for each component type. This means, that each component definition has to have a unique id, as well as variableName defined, needs to exactly match the name of the property, supported by a related component.

Below you can find a table of all supported properties of a component definition object

Component definition schema

Property	Required	Value Type	Default Value	Description
id	true	string	undefined	Unique arbitrary string. Will be used to identify the component that has to render at a certain place on a page. Allowed characters: alphanumeric, - and _. Max length = 32 characters.
name	true	string	undefined	User-friendly name of the registered component, which will be rendered to the user within the Experiences canvas.
category	false	string	undefined	Arbitrary string. All component definitions which have the same category value will be grouped together within the Experiences canvas.
children	false	boolean	false	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
thumbnailUrl	false	string	undefined	The image provided will be rendered within the registered component card in the Experiences canvas
variables	true	object	undefined	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.
builtInStyles	false	Array	['cfMargin']	For each value provided, the Experiences canvas UI will render a dedicated control, which for selecting a respective style value. Such style value will then be provided into the registered component as 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']. See Built-in styles for an example.
tooltip	false	object	undefined	The tooltip option adds an informational tooltip to the Component card element in the Components tab of the left 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.

Variable definition

Property	Required	Value Type	Default Value	Description
type	true	string	undefined	Data type of the prop, expected by a component. Possible values: Text, RichText, Number, Date, Boolean, Location, Media, Link, Array, Object, Hyperlink
validations	false	object	undefined	At the moment only in validation is implemented, which allows to define pre-defined values, which will be displayed in Experiences <select> control
group	false	string	'content'	Possible values: style, content. Marks a prop as a design variable if style is provided. Design variables get hardcoded in the experience entry 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.
description	false	string	undefined	Description to the variable. Can be a place to give a user friendly explanation of the variable's purpose. A hint will be rendered as part of the control in the Experiences UI
displayName	false	string	undefined	User friendly name of the prop. Will be rendered in Experiences UI
defaultValue	false	any	undefined	A value, which will be 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

Variable types in Experiences

Experiences divides all variables into two types: Design and Content.

Content variables

Content variables are variables that provide data for your components. Such data is part of your Data Domain and you are probably already storing it in Entries or Assets.

Values for such variables can be provided as one-offs, typing them manually, or could be instead taken by reference from existing Entries or Assets. We call such operation - Binding.

To make a variable a Content variable, set group to content in its variable definition.

Such variables are rendered in a specific tab - Content tab.

 

Design variables

Design variables are variables that allow to change visual representation of a component. We believe, that such values are not part of the Data Domain and hence should not be stored in Entries or Assets and can be set by the user for each component on the go.

To make a variable a Design variable, set group to style in its variable definition

Such variables are rendered in a specific tab - Design tab.