---
title: "Walkthrough: Building a simple custom component"
slug: "walkthrough--building-a-simple-custom-component"
abstract: "Create a custom component for XM Cloud in the Content Editor."
---
# Walkthrough: Building a simple custom component

> [!note]
> Use the Content Editor for the steps described in this topic.

XP comes with a set of default components for simple text, images, page content, and so on. You can also create a new component. This topic describes the tasks involved in creating a component. In this example, you create a component called *CustomComponent1* that renders a simple text field.

To help you decide whether you need to create a custom component, you can check this [flowchart](https://doc.sitecore.com/xp/en/developers/sxa/105/sitecore-experience-accelerator/flowchart-to-determine-whether-to-create-a-custom-rendering.html "Flowchart to determine whether to create a custom rendering").

This walkthrough describes how to:

- Create a JSON component item with a data source template and a rendering parameters template.
- Create a default variant for the component that renders a text field.
- Create a component file for your front-end JSS app that corresponds to the component item defined in the Content Editor.
- Add base templates to the parameters template of your component to ensure that the component supports the functionality you need.

## Create a JSON component item

Creating a custom component involves creating a JSON component, a rendering parameters template, and a data source template.

To create a JSON component item:

1. In the Content Editor, navigate to */sitecore/layout/Renderings/Feature*, right-click, and then click **Insert** > **Rendering Folder**. Enter a name, for example, *Custom Components*.
2. Right-click the *Custom Components* folder, click **Json Rendering**, and enter the name *CustomComponent1*.

    ![Create a JSON component in the Content Editor](https://doc.sitecore.com/api/markdown-image/xp/en/developers/sxa/105/sitecore-experience-accelerator/images/ce-add-json-component1.png)

3. Navigate to *sitecore/Templates/Feature*, right-click, and then click **Insert** > **Template Folder**. Enter the name *CustomTemplates*.
4. Right-click the *CustomTemplates* folder, and then click **Insert** > **New Template**.
5. In the dialog box, enter a name, for example, *MyParameters*, and select the *Templates/Foundation/Headless Experience Accelerator/Presentation/Rendering Parameters/Base Rendering Parameters* item. Select the *CustomTemplates* folder as the location for your parameters template and click **Next**.
6. Right-click the *CustomTemplates* folder, and then click **Insert** > **New Template**.
7. In the dialog, enter a name, for example, *MyDatasource*, and select the */Templates/System/Templates/Standard template* item. Select the *CustomTemplates* folder as the location for your data source template and click **Next**.
8. To add a text field named *SomeText* to the data source template, follow these steps:
    - Right-click *MyDatasource*, and then click **Insert** > **Template section**. Enter a name for the section. Or, click inside the **Add a new section** field on the **Builder** tab.
    - Click *MyDatasource* again and, on the **Builder** tab, click inside the field below the section you've just added.
    - Enter the name *SomeText* and select a field type, for example, *Rich Text*.

    ![Create a data source template and add a text field](https://doc.sitecore.com/api/markdown-image/xp/en/developers/sxa/105/sitecore-experience-accelerator/images/ce-add-datasource-parameters-templates.png)

9. In the content tree, navigate to the *CustomComponent1* component:
    - In the **Datasource Template** field, click **Insert link**, and select the *MyDatasource* item you've just created.
    - In the **Datasource Location** field, insert this query: *query:$site/\*\[@@name='Data'\]/\*\[@@name='CustomComponent1DataSources'\]|query:$sharedSites/\*\[@@name='Data'\]/\*\[@@name='CustomComponent1DataSources'\]*.

        ![ ](https://doc.sitecore.com/api/markdown-image/xp/en/developers/sxa/105/sitecore-experience-accelerator/images/ce-custom-component-datasource-template-location1.png)

## Create a default variant for the component

Components must have a default variant. In this example, you create a variant that renders a text field and name it, for example, *Default*. Later, when you create the component TSX file on the rendering host site, you will reference the **Default** variant using that exact name.

To create a default variant:

1. Navigate to *sitecore/Content/\[site collection\]/\[site\]*, right-click *Data*, and then click **Insert** > **Insert from Template**.
2. In the **Insert from Template** dialog, navigate to *Templates/Common* and select *Folder*. In the **Item Name** field, enter the name *CustomComponent1DataSources*. This folder is used to store the data sources of your component.
3. Navigate to *sitecore/Content/\[site collection\]/\[site\]/Presentation/Headless Variants* and click **Insert** > **Variants**. Enter the name *Custom Component Variant*.
4. Right-click *Custom Component Variant*, and then click **Insert** > **Variant Definition**. Enter the name *Default*. The name you give here must be consistent with the name used later in the component TSX file.

    ![Create the Default variant for a custom component](https://doc.sitecore.com/api/markdown-image/xp/en/developers/sxa/105/sitecore-experience-accelerator/images/ce-custom-component-default-variant.png)

## Create a TSX file for your component

Your front-end JSS app must have a JavaScript component that is consistent with the component you have just created in the Content Editor.

> [!note]
> The component TSX files are typically located in the following directory:
>
> *src/components*.

To create a TSX file for your component:

- In the directory where the TSX files are located, add a component file with the same name as the name you defined in the **Component Name** field of the component item. In this example, *CustomComponent1.tsx*:

    ![The Component Name field in the Content Editor](https://doc.sitecore.com/api/markdown-image/xp/en/developers/sxa/105/sitecore-experience-accelerator/images/ce-component-name-field.png)

    ![Example of a JSS component file](https://doc.sitecore.com/api/markdown-image/xp/en/developers/sxa/105/sitecore-experience-accelerator/images/custom-component-tsx-file.png)

The following example of a JavaScript component renders the `SomeText` field that you added to the data source item of the component:

> [!note]
> The exported method is called *Default* in accordance with the variant definition you created earlier.

```csharp
import React from 'react';

import { Field, Text } from '@sitecore-jss/sitecore-jss-nextjs';

interface Fields {

  SomeText: Field<string>;

}

type CustomComponent1Props = {

  params: { [key: string]: string };

  fields: Fields;

};

export const Default = (props: CustomComponent1Props): JSX.Element => {

  return (

    <div className={`component customcomponent1 ${props.params.styles}`}>

      <div className="component-content">

        <div>

          <Text field={props.fields.SomeText} />

        </div>

      </div>

    </div>

  );

};

```

## Add base templates to the parameters template

Depending on the functionality you want your component to support, you need to add certain base templates to the rendering parameters template of your component. For example, this is relevant if you want the component to support grids and styles, variants, and dynamic placeholders.

> [!note]
> Add the base templates required by the features your component supports. Optionally, add `_PerSiteStandardValues` only when you need site-specific standard values for the rendering-parameters template.



To add base templates to the parameters template:

1. Navigate to *sitecore/Templates/Feature/CustomTemplates* and click *MyParameters*.
2. On the **Content** tab, in the **Data** section, assign the base templates you need to the parameters template:
    - The */sitecore/templates/Foundation/Headless Experience Accelerator/Presentation/Rendering Parameters/Base Rendering Parameters* template includes these templates:
        - *IStyling* for styles support. This template adds a new field in the control properties for that component and an additional button on the edit frame of the component.
        - *IComponentVariant* for variant support. This template adds a variant drop-down in the control properties and Variant Selector drop-down on the edit frame.
        - *Grid Parameters* for grid support. This template adds a grid field in the control properties and an additional button on the edit frame of the component.
    - The */sitecore/templates/Foundation/Experience Accelerator/Dynamic Placeholders/Rendering Parameters/IDynamicPlaceholder* template supports dynamic placeholder keys by adding a placeholder in addition to, for example, a title or some text.
    - The */sitecore/templates/Foundation/Experience Accelerator/StandardValues/_PerSiteStandardValues* template supports site-specific standard values.

        > [!note]
        > Only add this base template if you are planning to use standard values for specific sites. This is to avoid unnecessarily affecting the performance.

    - The */sitecore/templates/Foundation/Experience Accelerator/Markup Decorator/Rendering Parameters/IRenderingId* supports HTML identifiers. This template adds an ID field to the component configuration, which renders an attribute to an element in the HTML code.

        ![Add base templates to a custom component](https://doc.sitecore.com/api/markdown-image/xp/en/developers/sxa/105/sitecore-experience-accelerator/images/ce-assign-base-template-to-rendering-parameters.png)