> This page is for Designer API.

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

# Create a component

## `webflow.registerComponent(options)`

## `webflow.registerComponent(options, root)`

## `webflow.registerComponent(options, source)`

## `webflow.registerComponent(name, root)`

Registers a new [component definition](/designer/reference/components-overview#component-definition) with the specified name and options.

* To create a component that is not inside any element, pass an object with the name for the new component and optionally a group and description. (Beta)

* To convert an existing element into a component, by default replacing the element with the new component, pass the options for the new component and the element to turn into a component. (Beta)

* To duplicate an existing component, pass the options for the new component and component to duplicate. (Beta)

* To create a component definition and insert it within an existing element, pass the name for the new component and the root element. (Deprecated)

### Syntax

Component options:

```typescript
interface ComponentOptions {
  /** The name of the component (required) */
  name: string;
  /** The group/folder to place the component in (optional) */
  group?: string;
  /** A description for the component (optional) */
  description?: string;
  /** Whether to replace the existing element (optional) */
  replace?: boolean;
}
```

Create a component that is not inserted onto the page (Beta):

```typescript
webflow.registerComponent(
  options: ComponentOptions
): Promise<Component>
```

Convert an existing element into a component, by default replacing the element with the new component (Beta):

```typescript
webflow.registerComponent(
  options: ComponentOptions,
  root: AnyElement | BuilderElement | ElementPreset<AnyElement>,
): Promise<Component>
```

Duplicate a component (Beta):

```typescript
webflow.registerComponent(
  options: ComponentOptions,
  source: Component | ComponentId,
): Promise<Component>
```

Create a component in an existing root element (Deprecated):

```typescript
webflow.registerComponent(
  name: string,
  root: AnyElement | ElementPreset<AnyElement> | Component
): Promise<Component>
```

### Parameters

* **`options`**: An object with these properties:

  * **`name`** :   *string* - The name of the component, which must not be empty and must be unique.
  * **`group`** :   *string* - (optional) The group/folder to place the component in.
  * **`description`** :   *string* - (optional) A description for the component.
  * **`replace`** :   *boolean* - (optional) Whether to replace the existing canvas element with the new component.
    This parameter applies only when `root` is a canvas `AnyElement`.
    The default is `true` when `root` is a canvas element.
    Passing `replace: true` when `root` is an `ElementPreset` or `BuilderElement` throws `InvalidRequest`.

* **`root`** :   *AnyElement | ElementPreset\<AnyElement> | BuilderElement* - The source element to convert into a component, which can be an existing element, an element preset, or a builder element.

* **`source`** :   *Component | ComponentId* - The component or component ID to duplicate.

If you omit the second parameter, the function creates a blank Block-based component.

### Returns

**Promise\< *Component*>**

A Promise that resolves to the registered component.

### Examples

```typescript
// Create a hero component in the Sections group that is not within an existing element
const hero = await webflow.registerComponent({
  name: 'Hero Section',
  group: 'Sections',
  description: 'A reusable hero section with heading and CTA',
});
```

```typescript
// Convert an existing element into a component and replace the element with the component
const selectedElement = await webflow.getSelectedElement()
if (selectedElement) {
  const heroComponent = await webflow.registerComponent(
    {
      name: 'Hero Section',
      group: 'Sections',
      description: 'Main hero with heading and CTA'
    },
    selectedElement
  )
}
```

```typescript
// Duplicate a component
const [original] = await webflow.getAllComponents()
const copy = await webflow.registerComponent({ name: 'Card Copy' }, original)
```

[Try this example](https://webflow.com/oauth/authorize?response_type=code\&client_id=19511de1ec410f9228d8dcbc9420e67916dea80d86d18f0c9a533eb475ea0f62)

---

### Designer Ability

| Designer Ability        | Locale  | Branch | Workflow | Sitemode |
| :---------------------- | :------ | :----- | :------- | :------- |
| **canCreateComponents** | Primary | any    | Canvas   | any      |