Migrating to v2

We’re excited to introduce the new version of Webflow’s Designer APIs, featuring enhanced functionality and more efficient methods for interacting with the Designer. To ensure your app remains compatible, please follow the simple steps provided for updating your app’s configuration and codebase. Check the details below.

Notable Changes

Simplified edit semantics

We have removed the .save() method from many of our objects. Rather than staging “local changes” and explicitly synchronizing via element.save(), we’re now making changes as they’re invoked.

Accessing native Elements

Through the introduction of the Element Presets Object, the API now allows Apps to insert native Elements onto the canvas.

Inserting Elements

We’re introducing new helper methods that make it easier to insert elements into a hierarchy

• element.append()
• element.prepend()
• element.before()
• element.after()

We’ve removed element-specific methods for adding an element to a canvas including

• createDOM()
• createString()
• createHeading()

Direct editing of Components

This API allows a more streamlined way to edit Component Objects, by accessing the root element of a Component Object.

Clear and consistent naming

We’ve made minor changes to clarify Designer API functionality

• “Folders” → “PageFolders” to disambiguate versus other Page resources (e.g. Asset pages)
• “og-” -> “openGraph-” prefix for Open Graph Page Fields

Clear and consistent return objects

• Most methods that aren’t meant to return a value now return a Promise that resolves to null instead of undefined
• Element IDs are now identified by their component and element ids, e.g. id: {component: '63486e4622e33733b9002e9c', element: 'cafe0045-d304-79d9-8f68-af3adaed06e8'}

App configuration Updates

1. Install the latest version of the Webflow CLI
2. Install the latest type definitions for the Designer APIs

$
npm i @webflow/designer-extension-typings@0.2.0-beta.3

3. Update webflow.json to include the new apiVersion parameter.

1
{
2
  "name": "My Webflow App",
3
  "publicDir": "dist",
4
  "apiVersion": "2"
5
}

4. Start your development server.

Code Adjustments

Remove any references to .save()

1
// v1
2
await myElement.setStyles([styles])
3
await myElement.save()
4
5
// v2
6
await myElement.setStyles([styles])

Adjust logic to access Element IDs

1
// v1
2
const selectedElement = await webflow.getSelectedElement()
3
console.log(selectedElement)
4
// Prints: 'cafe0045-d304-79d9-8f68-af3adaed06e8'
5
6
// v2
7
const selectedElement = await webflow.getSelectedElement()
8
console.log(selectedElement)
9
// Prints id: {component: '63486e4622e33733b9002e9c', element: 'cafe0045-d304-79d9-8f68-af3adaed06e8'}\`
10
11
const elementID = selectedElement?.id.element
12
// Returns: 'cafe0045-d304-79d9-8f68-af3adaed06e8'

Adjust logic for element insertion

1
// v1
2
const newDiv = await webflow.createDOM('div')
3
4
// v2
5
const selectedElement = await webflow.getSelectedElement()
6
const newDiv = await selectedElement?.before(webflow.elementPresets.DivBlock)