Was this page helpful?

Component definition schema

Component definition

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' | '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.

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, 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.