Framer Plugins with Components

https://www.framer.com/developers/plugins-with-components
Admin
This documentation describes how Framer plugins can insert, update, and manage component instances...
Tokens:1,971
Snippets:15
Trust Score:10
Update:8 months ago
Show doc for...
Tokens:
Raw
### Insert Component Instance with Control Attributes

Source: https://www.framer.com/developers/plugins-with-components/index

Shows how to insert a component instance and dynamically set its internal controls. This is useful for properties like setting a video URL for a video component.

```javascript
framer.addComponentInstance({
  url,
  attributes: {
    controls: {
      url: "https://path/to/video.mp4"
    }
  }
})
```

--------------------------------

### Inserting Component Instances

Source: https://www.framer.com/developers/plugins-with-components/index

This section details how to insert component instances into Framer projects using plugins. You can specify the component's module URL and customize its attributes, including control properties.

```APIDOC
## POST /framer/addComponentInstance

### Description
Inserts a component instance into the Framer project.

### Method
POST

### Endpoint
/framer/addComponentInstance

### Parameters
#### Request Body
- **url** (string) - Required - The module URL of the component to insert.
- **attributes** (object) - Optional - An object containing attributes to customize the component instance.
  - **width** (string) - Optional - The width of the component instance.
  - **height** (string) - Optional - The height of the component instance.
  - **controls** (object) - Optional - An object to set the properties of the component's controls.
    - **[controlName]** (any) - Description of the control property.

### Request Example
```json
{
  "url": "https://framer.com/m/framer/Video.js",
  "attributes": {
    "width": "900px",
    "height": "600px",
    "controls": {
      "url": "https://path/to/video.mp4"
    }
  }
}
```

### Response
#### Success Response (200)
- **instance** (object) - The inserted component instance.

#### Response Example
```json
{
  "instance": { /* ... component instance details ... */ }
}
```
```

--------------------------------

### Insert Component Instance with Size Attributes

Source: https://www.framer.com/developers/plugins-with-components/index

Demonstrates inserting a component instance with specified dimensions. The `attributes` object allows for setting properties like `width` and `height` for the component.

```javascript
framer.addComponentInstance({
  url,
  attributes: { width: "900px", height: "600px" }
})
```

--------------------------------

### Module URLs

Source: https://www.framer.com/developers/plugins-with-components/index

Explains Framer's Module URLs, which are unique identifiers for components used for sharing and insertion via plugins. Details how to obtain URLs for specific versions or the latest version.

```APIDOC
## Module URLs

### Description
Module URLs are unique identifiers for Framer components that allow them to be shared and inserted into projects via plugins. These URLs can point to a specific version of a component or to the latest version.

### Obtaining Module URLs
1. Locate your code component in the **Assets Panel**.
2. Right-click on the component and select **“Copy URL…”**.

### URL Formats
- **Specific Version URL:** `https://framer.com/m/ComponentName-XXXX.js@SaveIDString`
  - The `@SaveIDString` part ensures the URL always points to that exact version.
- **Latest Version URL:** `https://framer.com/m/ComponentName-XXXX.js`
  - Remove the `@` and the subsequent string to make the URL point to the latest published version of the component.
```

--------------------------------

### Insert Component Instance with URL

Source: https://www.framer.com/developers/plugins-with-components/index

Inserts a component instance into Framer using its module URL. This function requires the component's URL and can optionally accept attributes to customize the instance, such as size.

```javascript
const instance = await framer.addComponentInstance({
  url: "https://framer.com/m/framer/Video.js"
})
```

--------------------------------

### Inserting Detached Component Layers

Source: https://www.framer.com/developers/plugins-with-components/index

This section explains how to insert components as detached layers instead of instances. You can configure attributes and optionally enable a layout flag for breakpoint matching.

```APIDOC
## POST /framer/addDetachedComponentLayers

### Description
Inserts a component as detached layers into the Framer project.

### Method
POST

### Endpoint
/framer/addDetachedComponentLayers

### Parameters
#### Request Body
- **url** (string) - Required - The module URL of the component.
- **attributes** (object) - Optional - An object containing attributes to set for the detached layers.
  - **[attributeName]** (any) - Description of the attribute.
- **layout** (boolean) - Optional - If true, inserts layers as a layout section matching breakpoints.

### Request Example
```json
{
  "url": "https://framer.com/m/YourComponent.js",
  "attributes": {
    "title": "User Name"
  },
  "layout": true
}
```

### Response
#### Success Response (200)
- **frame** (object) - The created detached component layers.

#### Response Example
```json
{
  "frame": { /* ... frame details ... */ }
}
```
```

--------------------------------

### Updating Control Values

Source: https://www.framer.com/developers/plugins-with-components/index

This section covers how plugins can update control attributes on component nodes. It also includes steps for uploading images to be used in component controls.

```APIDOC
## POST /framer/selection/setAttributes

### Description
Updates the attributes of a selected component node, specifically focusing on control values.

### Method
POST

### Endpoint
/framer/selection/setAttributes

### Parameters
#### Request Body
- **controls** (object) - Required - An object containing the control properties to update.
  - **[controlName]** (any) - The value to set for the specified control.

### Request Example
```javascript
// Assuming 'selection' is a valid component node
selection.setAttributes({
  controls: {
    radius: 10
  }
});
```

## POST /framer/uploadImage

### Description
Uploads an image to Framer and returns an object that can be assigned to an image control.

### Method
POST

### Endpoint
/framer/uploadImage

### Parameters
#### Request Body
- **image** (string) - Required - The URL of the image to upload.
- **altText** (string) - Optional - Alternative text for the image.

### Request Example
```javascript
const image = await framer.uploadImage({
  image: "https://example.com/image.png",
  altText: "Alt Text"
});

// Then use the returned image object to set the control value
selection.setAttributes({
  controls: {
    image: image
  }
});
```

### Response
#### Success Response (200)
- **image** (object) - An object representing the uploaded image, suitable for assigning to controls.

#### Response Example
```json
{
  "image": { /* ... image object details ... */ }
}
```
```

--------------------------------

### Insert Detached Component Layers with Attributes

Source: https://www.framer.com/developers/plugins-with-components/index

Inserts component layers as detached layers rather than a component instance. This method also accepts an `attributes` object for customization, such as setting a title.

```javascript
const frame = await framer.addDetachedComponentLayers({
  url, 
  attributes: { title: user.name }
})
```

--------------------------------

### Insert Detached Component Layers with Layout Flag

Source: https://www.framer.com/developers/plugins-with-components/index

Inserts detached component layers and enables a layout flag. When `layout` is true, Framer attempts to align the component variants with the web page's breakpoints.

```javascript
framer.addDetachedComponentLayers({ url, layout: true })
```

--------------------------------

### Update Component Image Control

Source: https://www.framer.com/developers/plugins-with-components/index

Updates an image control within a component. This involves first uploading the image using `framer.uploadImage` and then assigning the returned image object to the 'image' control.

```javascript
const image = await framer.uploadImage({
image: "https://example.com/image.png",
altText: "Alt Text"
})
  
selection.setAttributes({
controls: {
image,
}
})
```

--------------------------------

### Update Component Control Attributes

Source: https://www.framer.com/developers/plugins-with-components/index

Updates the control attributes of a component node. This requires ensuring the selected node is a code component before attempting to set new control values, such as 'radius'.

```javascript
if (!isCodeComponentNode(selection)) return
  
selection.setAttributes({
controls: {
radius: 10,
}
})
```
Tokens:
Raw