> This page is for Studio.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful-staging.ferndocs.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful-staging.ferndocs.com/developers/docs/_mcp/server.

# Component definition

> View component definition and schema for Experiences components.

## Overview

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

```ts
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](https://github.com/contentful/experience-builder/blob/3d483466fb97740759e460fb4054b290ec94b5cb/packages/core/src/constants.ts#L73-L118).

## Component definition fields

### <ins>id</ins>

**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`

### <ins>name</ins>

**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`

### <ins>category</ins>

**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`

### <ins>children</ins>

**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`

### <ins>thumbnailUrl</ins>

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

**Required**: `false`

**Value type**: `string`

**Default value**: `undefined`

### <ins>tooltip</ins>

**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

### <ins>builtInStyles</ins>

**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**:

```Typescript
['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](/built-in-styles)

### <ins>variables</ins>

**Description**: Key-value pair, where key is the prop name (defined by component implementation) and value is [the variable definition](#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

### <ins>type</ins>

**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`

### <ins>validations</ins>

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

**Required**: `false`

**Default value**: `undefined`

**Type definition**:

```ts
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**:

```js
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',],
      }
    }
  },
}
```

### <ins>description</ins>

**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`

### <ins>displayName</ins>

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

**Required**: `false`

**Value type**: `string`

**Default value**: `undefined`

### <ins>defaultValue</ins>

**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`

### <ins>group</ins>

**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](#types).

**Possible values**: `style`, `content`

**Required**: `false`

**Value type**: `string`

**Default value**: `content`