Framer Developers Assets

https://www.framer.com/developers/assets
Admin
Documentation for Framer's developer assets, providing methods and examples for programmatically...
Tokens:4,026
Snippets:25
Trust Score:10
Update:8 months ago
Show doc for...
Tokens:
Raw
### Process Image Bytes using HTML Canvas in Framer

Source: https://www.framer.com/developers/assets/index

Demonstrates how to process raw image bytes using an HTML canvas in Framer. It involves getting a selected image, loading its bitmap, drawing it onto a canvas (with an example of horizontal inversion), and then converting the canvas content back into image bytes for re-uploading.

```javascript
// Get the selected image in framer
const image = await framer.getImage()

const canvas = document.createElement("canvas")
const ctx = canvas.getContext("2d")

// Load the image bytes into an ImageBitmap that canvas supports
const bitmap = await image.loadBitmap()

// Set the height of the canvas to the height of the image
ctx.canvas.width = img.width;
ctx.canvas.height = img.height;

// Here we horizontally invert the image bitmap.
ctx.scale(-1, 1);
ctx.drawImage(bitmap, -bitmap.width, 0);

const result = await bytesFromCanvas(canvas);

await framer.addImage({
  image: { bytes: result, mimeType },
});
```

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

### Get Image from Framer Selection

Source: https://www.framer.com/developers/assets/index

Retrieves the image of the current selection in Framer. This function is the simplest way to get an image from the canvas.

```javascript
const image = await framer.getImage();
```

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

### Add SVG (under 10kb)

Source: https://www.framer.com/developers/assets/index

This function allows you to add SVG elements to your project. The SVG HTML content and a chosen name can be provided. Only SVGs smaller than 10kb are accepted.

```APIDOC
## POST /addSVG

### Description
Adds an SVG element to the project with a given name. Accepts SVGs smaller than 10kb.

### Method
POST

### Endpoint
/addSVG

### Parameters
#### Request Body
- **svg** (string) - Required - The HTML content of the SVG.
- **name** (string) - Required - The name to assign to the SVG.

### Request Example
```json
{
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"20\" height=\"20\"><path d=\"M5 2.5h10v5h-5Zm0 5h5l5 5H5Zm5 5v5l-5-5Z\"/></svg>",
  "name": "framer.svg"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "SVG added successfully"
}
```
```

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

### File Upload and Assignment API

Source: https://www.framer.com/developers/assets/index

This section covers the process of uploading files to Framer and assigning them to code component controls. It details the `uploadFile` method and how to use the uploaded file reference when creating component instances.

```APIDOC
## uploadFile

### Description
Uploads a file to Framer. This file can then be assigned to a code component's property controls.

### Method
`framer.uploadFile(options)`

### Parameters
#### Request Body
- **file** (string | File) - Required - The file to upload. Can be a URL or a File object.
- **name** (string) - Optional - The name of the file.

### Request Example
```javascript
const uploadedFile = await framer.uploadFile({
  file: "https://example.com/video.mp4",
  name: "Example Video"
})
```

## addComponentInstance

### Description
Inserts a component instance into the Framer canvas. This can include assigning uploaded files to component controls.

### Method
`framer.addComponentInstance(options)`

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the component.
- **attributes** (object) - Required - The attributes for the component instance.
  - **controls** (object) - The controls for the component.
    - **srcType** (string) - The type of the source, e.g., "Upload".
    - **srcFile** (object) - The uploaded file object.

### Request Example
```javascript
// Insert a Video Component with the uploaded file
await framer.addComponentInstance({
  url: "https://framer.com/m/framer/Video.js#Video",
  attributes: {
    controls: {
      srcType: "Upload",
      srcFile: uploadedFile,
    },
  },
})
```
```

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

### Upload File to Framer and Assign to Component

Source: https://www.framer.com/developers/assets/index

Uploads a file (e.g., a video) to Framer and then assigns it to a component's control. This is achieved using `framer.uploadFile` and `framer.addComponentInstance`.

```javascript
const uploadedFile = await framer.uploadFile({
// You can also pass "File" objects
// To accept <input type="file" /> inputs.
file: "https://example.com/video.mp4",
name: "Example Video"
})
  

// Insert a Video Component with the uploaded file
await framer.addComponentInstance({
url: "https://framer.com/m/framer/Video.js#Video",
attributes: {
controls: {
srcType: "Upload",
srcFile: uploadedFile,
},
},
})
```

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

### Image Management API

Source: https://www.framer.com/developers/assets/index

This section details the methods for adding, setting, and manipulating images within Framer. It covers uploading images via URL or file input, applying them to the canvas or selected nodes, and managing image resolution.

```APIDOC
## addImage

### Description
Adds an image to the canvas. This can be done by providing a URL or a File object. You can also specify a name, alt text, and resolution.

### Method
`framer.addImage(options)`

### Parameters
#### Request Body
- **image** (string | File | { bytes: Uint8Array, mimeType: string }) - Required - The image source. Can be a URL, a File object, or an object containing image bytes and mime type.
- **name** (string) - Optional - The name of the image.
- **altText** (string) - Optional - The alternative text for the image.
- **resolution** (string) - Optional - The resolution of the image. Allowed values: "auto", "lossless", "small", "medium", "large", "full". Defaults to "auto".

### Request Example
```javascript
// Upload an image with a URL
await framer.addImage({
  image: "https://example.com/image.png",
  name: 'My image',
  altText: "Alt description"
})

// Add an image through a file input
const fileInput = document.querySelector(`input[type="file"]`)
const file = fileInput.files[0]

const image = await framer.addImage({
  image: file, 
  name: "Uploaded image", 
  altText: "Alt Description" 
})

// or use the shorthand
const image = await framer.addImage(file)
```

## setImage

### Description
Sets an image on the currently selected node or a component node with an Image control prop.

### Method
`framer.setImage(options)`

### Parameters
#### Request Body
- **image** (string | File | { bytes: Uint8Array, mimeType: string }) - Required - The image source.
- **altText** (string) - Optional - The alternative text for the image.

### Request Example
```javascript
await framer.setImage({ image: "https://example.com/image.png", altText: "Alt Description" })
```

## uploadImage

### Description
Uploads an image to Framer without assigning it to a node. The uploaded image can be used later for creating nodes.

### Method
`framer.uploadImage(options)`

### Parameters
#### Request Body
- **image** (string | File | { bytes: Uint8Array, mimeType: string }) - Required - The image source.
- **name** (string) - Optional - The name of the image.
- **altText** (string) - Optional - The alternative text for the image.

### Request Example
```javascript
const image = await framer.uploadImage({
  image: 'https://example.com/image.png',
  name: 'My image',
  altText: "alt Description"
})
```

## getImage

### Description
Gets the image of the current selection if it exists.

### Method
`framer.getImage()`

### Response
#### Success Response (200)
- **image** (ImageAsset | null) - The selected image asset or null if no image is selected.

### Request Example
```javascript
const image = await framer.getImage();
```

## subscribeToImage

### Description
Subscribes to image changes on the selection. Returns an unsubscribe function.

### Method
`framer.subscribeToImage(callback)`

### Parameters
#### Query Parameters
- **callback** (function) - Required - A function that will be called with the new image asset whenever the selection changes.

### Request Example
```javascript
import { framer, ImageAsset } from 'framer-plugin'

function useImageSelection() {
    const [image, setImage] = useState<ImageAsset | null>(null)
    useEffect(() => {
        return framer.subscribeToImage(setImage)
    }, [])
    return image
}
```

## Modifying Alt Text

### Description
Modifies the alt text of an image without changing the image itself. This is done by getting nodes with a `backgroundImage` attribute and updating their attributes.

### Method
`imageNode.setAttributes(attributes)`

### Request Example
```javascript
const imageNodes = await framer.getNodesWithAttributeSet("backgroundImage")
for (const imageNode of imageNodes) {
    if (!imageNode.backgroundImage) continue

    await imageNode.setAttributes({
        backgroundImage: imageNode.backgroundImage.cloneWithAttributes({
          altText: "Updated Alt Text"
        }),
    })
}
```

## Image Processing with Canvas

### Description
Provides utilities for performing image manipulation by rendering image bitmaps on an HTML canvas. This allows for operations like inverting an image.

### Method
`bytesFromCanvas(canvas)`

### Request Example
```javascript
// Get the selected image in framer
const image = await framer.getImage()

const canvas = document.createElement("canvas")
const ctx = canvas.getContext("2d")

// Load the image bytes into an ImageBitmap that canvas supports
const bitmap = await image.loadBitmap()

// Set the height of the canvas to the height of the image
ctx.canvas.width = img.width;
ctx.canvas.height = img.height;

// Here we horizontally invert the image bitmap.
ctx.scale(-1, 1);
ctx.drawImage(bitmap, -bitmap.width, 0);

const result = await bytesFromCanvas(canvas);

await framer.addImage({
  image: { bytes: result, mimeType },
});
```
```

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

### Add Image (for SVGs > 10kb)

Source: https://www.framer.com/developers/assets/index

For SVGs larger than 10kb, use the `addImage` function. This method accepts the SVG's byte data and MIME type.

```APIDOC
## POST /addImage

### Description
Adds an image to the project, suitable for SVGs larger than 10kb by accepting byte data.

### Method
POST

### Endpoint
/addImage

### Parameters
#### Request Body
- **image** (object) - Required - Image data.
  - **type** (string) - Required - Must be "bytes".
  - **bytes** (Uint8Array) - Required - The byte representation of the image.
  - **mimeType** (string) - Required - The MIME type of the image (e.g., "image/svg+xml").
- **name** (string) - Required - The name to assign to the image.

### Request Example
```json
{
  "image": {
    "type": "bytes",
    "bytes": "new TextEncoder().encode(svgInput)",
    "mimeType": "image/svg+xml"
  },
  "name": "SVG"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Image added successfully"
}
```
```

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

### Framer Image Selection Subscription Hook

Source: https://www.framer.com/developers/assets/index

A React hook that subscribes to image changes in Framer. It uses `useState` and `useEffect` to manage the image state and listen for updates via `framer.subscribeToImage`.

```javascript
import { framer, ImageAsset } from 'framer-plugin'

function useImageSelection() {
    const [image, setImage] = useState<ImageAsset | null>(null)
    useEffect(() => {
        return framer.subscribeToImage(setImage)
    }, [])
    return image
}
```

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

### Set Image Resolution in Framer

Source: https://www.framer.com/developers/assets/index

Allows setting the image resolution when adding or manipulating images in Framer. Supported resolutions include 'auto', 'lossless', 'small', 'medium', 'large', and 'full'.

```javascript
await framer.addImage({ image: "https://example.com/image.png", resolution: "lossless" })
```

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

### Set Image on Selected Node in Framer

Source: https://www.framer.com/developers/assets/index

Applies an image to the currently selected node in Framer. This method works for nodes that support setting an image or for Component Nodes with a single Image control prop.

```javascript
await framer.setImage({ image: "https://example.com/image.png", altText: "Alt Description" })
```

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

### Add Small SVG using addSVG Function

Source: https://www.framer.com/developers/assets/index

Adds an SVG to Framer using the `addSVG` function. Accepts SVG HTML and a name. Only SVGs smaller than 10kb are accepted. Requires the `framer` object to be available.

```javascript
await framer.addSVG({
svg: `<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20"><path d="M5 2.5h10v5h-5Zm0 5h5l5 5H5Zm5 5v5l-5-5Z"/></svg>`,
name: "framer.svg",
})
```

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

### Add Large SVG using addImage Function

Source: https://www.framer.com/developers/assets/index

Adds an SVG larger than 10kb to Framer by passing its byte data using the `addImage` function. Requires the `framer` object and `TextEncoder` to be available.

```javascript
await framer.addImage({
image: {
type: "bytes",
bytes: new TextEncoder().encode(svgInput),
mimeType: "image/svg+xml",
},
name: "SVG",
});
```

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

### Add Image to Framer Canvas

Source: https://www.framer.com/developers/assets/index

Adds an image to the Framer canvas using a URL or a File object. Supports specifying image name, alt text, and resolution. The `addImage` method can also accept a File object directly.

```javascript
await framer.addImage({
  image: "https://example.com/image.png",
  name: 'My image',
  altText: "Alt description"
})

const fileInput = document.querySelector(`input[type="file"]`)
const file = fileInput.files[0]

const image = await framer.addImage({
  image: file,
  name: "Uploaded image",
  altText: "Alt Description"
})

// or use the shorthand
const image = await framer.addImage(file)
```

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

### Upload Image to Framer Without Assigning

Source: https://www.framer.com/developers/assets/index

Uploads an image to Framer without immediately assigning it to a node. The uploaded image can later be used for creating new nodes.

```javascript
const image = await framer.uploadImage({
  image: 'https://example.com/image.png',
  name: 'My image',
  altText: "alt Description"
})

// Later, use the image for creating a node
await framer.createFrameNode({
  backgroundImage: image
})
```

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

### Modify Image Alt Text in Framer

Source: https://www.framer.com/developers/assets/index

Updates the alt text of an image node in Framer without changing the image itself. It retrieves nodes with a 'backgroundImage' attribute and uses `cloneWithAttributes` to modify the alt text.

```javascript
const imageNodes = await framer.getNodesWithAttributeSet("backgroundImage")
for (const imageNode of imageNodes) {
    if (!imageNode.backgroundImage) continue

    await imageNode.setAttributes({
        backgroundImage: imageNode.backgroundImage.cloneWithAttributes({
          altText: "Updated Alt Text"
        }),
    })
}
```
Tokens:
Raw