# Using Custom Components

Custom components in ThemeBuilder allow you to enrich your set of UI components by adding new ones. These custom components are based on pure HTML and can be styled using the built-in features and capabilities of ThemeBuilder.

The following characteristics define the custom components concept in ThemeBuilder:

* You can create custom components in all types of ThemeBuilder projects—projects created from scratch (blank) and projects starting from Telerik and Kendo UI themes.
* They consist of pure HTML code.
* Their HTML must have a single root element with a unique `class` attribute.
* They expose HTML elements for styling when you set a `class` attribute to them.

## Creating a Custom Component

To create a custom component:

1. Open an existing ThemeBuilder project and click the **+ Add Component** button.

  <img src="/themebuilder/documentation/assets/11a65d4d082fe9d6f86ea4a0fe94cb0d/add-component-canvas.png" alt="Add custom component in ThemeBuilder" style="width: 1200px;"/>

```
> If your project is based on a Telerik and Kendo UI theme, adding your first custom component creates a new **My Components** section. This section contains all custom components and the **+ Add Component** button.
```

1. In the **ADD COMPONENT** popup:
   * Enter a name for the new component, for example, `Login Form`.
   * Enter a **category** or choose an existing one from the categories list.

       <img src="/themebuilder/documentation/assets/88d290988c4f196644e80ff4bb3f2107/add-custom-component-popup.png" alt="Add custom component popup" style="width: 520px;"/>

> If you have a Telerik and Kendo UI Accelerator subscription, you'll see an additional button named **Start From Building Block**. This button allows you to select and customize a building block from the [included presets](https://www.telerik.com/page-templates-and-ui-blocks#building-blocks).

1. Select **Add Component** to add the new custom component.

## Adding or Editing Custom Component HTML Content

To add initial HTML or edit existing custom component HTML content:

1. With your custom component on the screen, select **Advanced Edit**.
2. Drill down to the desired custom component.
3. Open the [**Code Editor**](https://www.telerik.com/themebuilder/documentation/building-visual-styles/custom-components#using-the-code-editor).

   * If adding initial content to your custom component, select **Add HTML**.

    <img src="/themebuilder/documentation/assets/44c0fcdee532ef7394be79a3dc0eb2b9/add-html.png" alt="Add custom component HTML" style="width: 1200px;"/>

   * If updating HTML content in an existing custom component, select **Edit HTML**.

    <img src="/themebuilder/documentation/assets/bf0d7bcee695ba8975f7c8711b6afa00/edit-html.png" alt="Edit custom component HTML" style="width: 1200px;"/>
4. Type or paste the HTML content of the component.

> When editing custom component HTML, the `id` attributes are used internally by ThemeBuilder. The exported custom components HTML will not include them.

1. Select **Save** or **Save & Close** once you are done with the changes.

## Using the Code Editor

ThemeBuilder incorporates a code editor that allows you to easily manage the HTML content of your custom components. The editor consists of two main parts to ensure comprehensive and fast code input, validation, and preview.

* HTML code editor—the left pane is an HTML code editor. Use it to type (or paste existing) HTML code with IntelliSense and common development keyboard shortcuts. The editor validates the HTML periodically and lists warnings or errors at the bottom of the pane when needed.
* Code preview—the right pane is the code preview area. It gives you a real-time preview of the HTML input with all existing styles that match the HTML classes already applied.

  <img src="/themebuilder/documentation/assets/b09ac6d476ef9e374fb1d5642da0e57a/code-editor.png" alt="Custom component code editor" style="width: 1200px;"/>

## Managing Custom Components

To manage and organize custom components:

1. With your custom components on the screen, select **Advanced Edit**.
2. Hover over the drill-down container with the desired component and click the context menu button.

  <img src="/themebuilder/documentation/assets/cad02e81563be06f0822b1fd5dfe8447/manage-custom-component.png" alt="Manage custom components" style="width: 453px;"/>
1. Select the desired action:
  * Click **Rename** to change the custom component name and/or category.
  * Click **Delete** to delete it from your custom UI components set.
  > If the component is used in another one for [composition and reusability](#custom-components-reusability--composition), the component cannot be deleted.

## Rename Custom Component Parts

Each custom component element with a set `class` attribute is exposed for styling in ThemeBuilder. Initially, it appears in the component parts tree with a default name. To improve readability and management, you can change the default names to logically match the HTML elements.

1. With your custom components on the screen, select **Advanced Edit**.
2. Drill down to the desired custom component.
3. Select the part you want to rename in the components tree on the right side of the screen.
4. Click the **...** button to open the context menu.
5. Select **Rename**.
6. Enter the new name of the component part and press Enter.

  <img src="/themebuilder/documentation/assets/a5af4c0f1bfe2e240e2f01158a568679/rename-custom-component-part.png" alt="Rename custom component part" style="width: 1200px;"/>

## Custom Components Reusability and Composition

Modern UI frameworks rely on component composition to reuse existing components and build more complex ones quickly. ThemeBuilder also supports this concept.

To reuse already existing custom or Telerik and Kendo UI components:

1. Create a new custom component or open an existing one where you want to reuse other UI components.

2. Select **Add/Edit HTML**.

3. Place the cursor where you want to insert another component.

4. In the Code Editor:

   * Type `ct-` to view a list of all existing custom components that can be inserted.
     <img src="/themebuilder/documentation/assets/4e2e9ea92975c01c7ede92c2e66c82f2/reuse-custom-component.png" alt="Reuse custom components" style="width: 843px;"/>
   * If your project is based on a Telerik and Kendo UI theme, type `kendo-` to view a list of all Telerik and Kendo UI components that can be inserted.

     <img src="/themebuilder/documentation/assets/b164343ef25c4480e2a3bde9880e792a/reuse-kendo-component.png" alt="Reuse Telerik and Kendo UI components" style="width: 843px;"/>

   > When your project contains [Kendo component configurations](https://www.telerik.com/themebuilder/documentation/working-with-kendo/component-variants#adding-component-configuration), you can use them in your custom component HTML by typing `kendo-` followed by the name of the configuration and its configuration options (border radius, fill mode, size, and theme color). For example, a specific configuration of the **Large Primary Button** applying large size solid primary button with medium rounded corners exists in the Telerik and Kendo UI list of reusable components as `kendo-large-primary-button-medium-solid-large-primary`.

5. Select the component you want to insert from the list.

The HTML preview on the right shows the reused component with all its styles applied. When done editing the HTML, select **Save & Close**.

## Styling Custom Components

Consider the following when styling a custom component:

* To style an HTML element in a custom component, the element must have a `class` attribute with one or more classes set.
* Styling custom components works in the same way as with the Telerik and Kendo UI components. For more details, see the [Advanced Customization](https://www.telerik.com/themebuilder/documentation/building-visual-styles/apply-advanced-customizations) article.
* You can reuse classes from other custom components and all styles attached to them will be applied. For example, if you have a FormInput component with a `sample-form-input` class, you can create a FormEmailInput component and apply this class to inherit all its styles.
* To specifically style a component that reuses other component classes, set a component-specific class to it. In the prior example, to specifically style the FormEmailInput component and inherit from FormInput, apply `sample-form-input sample-form-email-input` classes to the FormEmailInput component.

## Custom Components in the Exported Package

If you have custom components within your project, the [exported ZIP package](https://www.telerik.com/themebuilder/documentation/using-exported-styles/exported-package#using-the-custom-components-output) contains their HTML content and styles.

For example, the HTML content of the *Login Form* component mentioned earlier would be included in the `<ZIP PACKAGE>/custom-components/login-form.html` file. It would be structured as follows:

```HTML
<form class="sample-form">
  <h1 class="sample-header">
    Log in to the Demo App
  </h1>
  <div class="sample-form-content">
    
    
  </div>
  
</form>
```

If your project is [based on a Kendo UI theme](https://www.telerik.com/themebuilder/documentation/get-started/first-steps-kendo) and includes custom components that reuse existing Telerik and Kendo UI components (for example, the *Login Form* uses the [Button component](https://www.telerik.com/themebuilder/documentation/working-with-kendo/tutorials/unique-look-button) as the action button), these Telerik and Kendo UI components will be replaced with comments in the generated HTML file:

```HTML
 <form class="sample-form">
  <h1 class="sample-header">
    Log in to the Demo App
  </h1>
  <div class="sample-form-content">
    
    
  </div>
  
</form>
```

If you export custom components through the [ThemeBuilder Figma plugin](https://www.telerik.com/themebuilder/documentation/plugin/exporting-components), and these custom components include images (either through the CSS property `background-image` or through an `<img>` tag), the utilized image files will be placed in the `<ZIP PACKAGE>/images/` directory of the exported package.

## Related Articles

* [Applying Advanced Customizations](https://www.telerik.com/themebuilder/documentation/building-visual-styles/apply-advanced-customizations)
* [Using the Exported ThemeBuilder Package](https://www.telerik.com/themebuilder/documentation/using-exported-styles/exported-package)
* [Export Components](https://www.telerik.com/themebuilder/documentation/plugin/exporting-components)