Component definition
Table of contents
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](link to next section)
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
