DocsAPIsChangelogResourcesMarketplace
Search

The Webflow Object

The webflow global object is your main access point to Webflow's Designer APIs. It provides methods to interact with the Webflow Designer and work with different types of elements in the canvas. These methods cover various tasks, such as retrieving site information, working with elements and styles, managing pages and folders, and handling events.

Understanding the Webflow Object is fundamental to leveraging the full power of the Webflow Designer API.

Methods

Meta

Get Site Information

getSiteInfo(): Promise<{siteId: string; siteName: string}>

Description: Get metadata about the current Site.

Returns: A Promise that resolves to a record containing information about the site that is open in the Designer - with the following properties

  • siteId : string - The unique ID of the current Webflow site.
  • siteName: string - The name of the current Webflow site.
  • shortName: string - A shortened reference to the name of the current Webflow site.
const siteInfo = await webflow.getSiteInfo();
console.log('Site ID:', siteInfo.siteId);
console.log('Site Name:', siteInfo.siteName);
console.log('Shortened Site Name:', siteInfo.shortName);

Elements & Breakpoints

Get Selected Element

getSelectedElement(): Promise<null | AnyElement>

Description: Get the currently selected element in the Webflow designer.

Returns : A promise that resolves to one of the following:

  • null: If no element is currently selected in the designer
  • AnyElement: an object representing the selected element, which can be of any type.
const selectedElement = await webflow.getSelectedElement();
if (selectedElement) {
  // Handle the selected element
} else {
  // No element is currently selected
}

Get All Elements

getAllElements(): Promise<Array<AnyElement>>

Description: Fetch an array of all elements present on the current page of the Designer. If the Designer is editing a component, the elements returned are those present in that Component.

Returns: A Promise that resolves to an array of AnyElement objects. AnyElement represents various element types available in a Webflow project. Each element type corresponds to different types of HTML elements or components that can be used within the designer. You can see a full list of supported elements in our designer extensions typing file.

const allElements = await webflow.getAllElements()
const paragraphs = allElements.flatMap(el => el.type === 'Paragraph' ? [el] : [])
paragraphs.forEach(el => {
  el.setTextContent('Hello')
  el.save()
})

Get Root Element

getRootElement(): Promise<null | AnyElement>;

Description: Get Root element. When the designer is focused or "entered" into a Component, this method will get the outermost element in the Component.

Returns: The outermost element of the Page or Component.

// 🎉 Enter into  Component 🎉
await webflow.enterComponent(heroComponentInstance)
const root = await webflow.getRootElement()

// Example Response
{id: '204d04de-bf48-5b5b-0ca8-6ec4c5364fd2'}

Get Breakpoint

getMediaQuery(): Promise<BreakpointId>

Description:: Get the current media query breakpoint ID.

Returns: A Promise that resolves to a BreakpointId which is a string representing the current media query breakpoint. A BreakpointId is one of 'tiny', 'small', 'medium', 'main', 'large', 'xl', 'xxl'.

const breakpoint = await webflow.getMediaQuery();
console.log('Current Media Query:', breakpoint);

Create DOM Element

📘

This is the main way of creating objects on the Canvas. See our reference information for the custom DOMElement.

createDOM(tag: string): DOMElement

Description: Create a custom HTML element with the specified tag.

Parameters:

  • tag: string - The HTML tag for the custom element.

Returns: A DOMElement object representing the newly created custom element.

const newDiv = webflow.createDOM('div')
// Use the newDiv object

Create Text Element

createString(text: string): StringElement

Description: Creates a new StringElement

Parameters:

  • Text:string- The string you'd like to create

Returns A StringElement object representing the newly created string.

const stringElement = webflow.createString("Hello world");
// add the string to a parent element (eg. a <div>)
parentElement.setChildren([stringElement]);

Create Heading

createHeading(tag: h1 | h2 | h3 | h4 | h5 | h6): HeadingElement

Description: Creates a new heading element with the provided level (h1-h6)

Parameters: tag: (1 | 2 | 3 | 4 | 5 | 6) - The heading level for the new heading element.

ReturnsHeadingElement object representing the new heading element.

const newH1 = webflow.createHeading(1)
// Use the newH1 object

Components

Webflow Components are customizable blocks of Elements, which can be reused across sites and managed in a central place. The Webflow object allows you to create, read, delete, enter, and exit a Component. To understand more about using the Components API, check out our in-depth documentation.

Get All Components

getAllComponents(): Promise<Array<Component>>

Description: Fetch all Site-scoped components definitions. In order to edit a component, you’ll need to get a specific Component instance.

Returns: A Promise resolving to an array containing all Components from the currently open site in the Designer - with the id property.

 const fetchedComponents = await webflow.getAllComponents()
 
// Example Repsonse
[
{id: "4a669354-353a-97eb-795c-4471b406e043"}
{id: 'd6e076e2-19a2-c4ae-9da3-ce3b0493b503'}
]

Create a Component

registerComponent(name: string, rootElement: AnyElement): Promise<Component>;

Description: Create a component by promoting a Root Element

Parameters:

  • name: string - Name of the component
  • rootElement: AnyElement - An Element that will become the Root Element of the Component

Returns: A Promise resolving to an object containing the newly created Component - with the id property.

const element = webflow.createDOM('div')
await webflow.registerComponent('Hero-Component', element)

// Example Response
{id: '204d04de-bf48-5b5b-0ca8-6ec4c5364fd2'}

Delete a Component

unregisterComponent(component: Component): Promise<void>;

Description: Delete a component from the Designer. If there are any instances of the Component within the site, they will be converted to regular Elements.

Parameters:

  • component: Component - The component object you wish to delete

Returns: A Promise resolving that resolves when the Component is deleted.

const element = webflow.createDOM('div')
const heroComponent = await webflow.registerComponent('Hero-Component', element)
await webflow.unregisterComponent(heroComponent)

Create a Component Instance

createInstance(component: Component): ComponentElement

Description: Render an Instance of the Component on a page.

Parameters:

  • component: Component- The Component object you’d like to create an Instance of.

Returns: A ComponentElement object better known as a Component Instance

// 🎉 Create Component 🎉
const element = webflow.createDOM('div')
const heroComponent = await webflow.registerComponent('Hero-Component', element)
// 🎉 Create Component instance 🎉
const heroComponentInstance = webflow.createInstance(heroComponent);

Enter a Component

enterComponent(instance: ComponentElement): Promise<void>;

Description: Focus the designer on a Component. When a component is in focus, all Globals pertain specifically to that Component, not the entire Site.

Parameters

  • instance: ComponentElement A Component Instance that is present on the page. If there’s no current instance, you’ll need to create one first.

Returns: A Promise that resolves when the page switch is successful.

    await webflow.enterComponent(heroComponentInstance)

Exit a Component

enterComponent(instance: ComponentElement): Promise<void>;

Description: Return to the broader context of the entire site or page.

Returns: A Promise that resolves when the page switch is successful.

      await webflow.exitComponent()

// 🎉 Enter into  Component 🎉
await webflow.enterComponent(heroComponentInstance)
const root = await webflow.getRootElement()

// Example Response
{id: '204d04de-bf48-5b5b-0ca8-6ec4c5364fd2'}

Styles

Create Style

createStyle(name: string): Style

Description: Creates a new style with the provided name

Parameters:

  • name :
    string
    • The name for the new style.

Returns: a Style object representing the newly created style.

const newStyle = webflow.createStyle('myNewStyle');

Note: To save the style to the Designer, call myNewStyle.save().

Get Style by Name

getStyleByName(name: string): Promise<null | Style>

Description:Fetch a style by its name.

Parameters:

  • name: string - The name of the stye to retrieve

Returns: A Promise that resolves to one of the following:

  • null: If no style with the given name is found.
  • Style: The Style object representing the style with the specified name.
const styleName = 'myStyle';
const style = await webflow.getStyleByName(styleName);
if (style) {
  // Style found, handle it
} else {
  // Style not found
}

Get All Styles

getAllStyles(): Promise<Array<Style>>

Description: Fetch an array of all styles available in the Webflow project.

Returns: A Promise that resolves to an array of Style objects representing all the styles present on the site that is open in the Designer.

const allStyles = await webflow.getAllStyles();
allStyles.forEach((style) => {
  // Process each style
});

Variables & Collections

Get Default Variable Collection

getDefaultVariableCollection(): Promise<null | VariableCollection>;

Description: Access the default variable collection

Returns: A Promise that resolves into a Collection.

const collection = webflow.getDefaultVariableCollection()
// This collection object can now be used to create variables or access variables within it

const variable = collection.getVariableByName('Space Cadet')

Pages & Folders

Get Current Page

getCurrentPage(): Promise<Page>

Description: Fetch the currently active page in the Webflow designer.

Returns:A Promise that resolves to a Page object representing the current page open in the Designer.

const currentPage = await webflow.getCurrentPage();
console.log('Current Page:', currentPage);

Get All Pages & Folders

getAllPagesAndFolders(): Promise<Array<Page | Folder>>

Description: Fetch an array of all pages and folders in the Webflow project.

Returns: Returns a Promise that resolves to an array of Page and Folder objects representing all the pages and folders of the site that is open in the Designer.

const items = await webflow.getAllPagesAndFolders();
items.forEach((item) => {
  // Process each page or folder
});

Create Folder

createFolder(): Promise<Folder>

Description: Create a new folder within the current Webflow project.

Returns: A Promise that resolves to a Folder object representing a newly created folder for the site open in the Designer.

const newFolder = await webflow.createFolder();
// Handle the new folder

Create Page

createPage(): Promise<Page>

Description: Create a new Page within the current Webflow project.

Returns: A Promise that resolves to a Page object representing a newly created page for the site open in the Designer.

const newPage = await webflow.createPage();
// Handle the new page

Switch Page

switchPage(page: Page): Promise<void>

Parameters:

  • page - Page- The Page object representing the target page to switch to.

Returns:A Promise that resolves when the page switch is successful.

const targetPage = /* Get the target page */;
await webflow.switchPage(targetPage);
// Page switched successfully

User Actions

Notify

notify(opts: { type: 'Error' | 'Info' | 'Success'; message: string; }): Promise<void>;

Description: Notifies the user with a message using a specific style. Error messages provide user's with the opportunity to close the Designer Extension.

Parameters:

  • opts: object - An object containing the following notification options:
    • type: ('Error' | 'Info' | 'Success'): The type of notification
    • message: string: The message to display in the notification

Returns: A Promise that resolves when the notification is displayed to the user.

webflow.notify({ type: 'Info', message: 'Great work!' }) // General notification
webflow.notify({ type: 'Error', message: 'Something went wrong, try again!' }) // Error notification
webflow.notify({ type: 'Success', message: 'Successfully did something!' })

Subscribing to events with callbacks

Callbacks are used to handle and respond to events triggered by the Webflow designer or any other asynchronous actions that may take place while interacting with the Webflow platform.

This allows you to decouple event handling from event triggering. Instead of continuously polling for changes or manually checking for updates, you can simply register your callbacks and let the Webflow API notify you when something important happens.

Subscribe to an event

subscribe(event, callback: (element: null | AnyElement) => void): Unsubscribe

Description: Allows you to register your custom functions (callbacks) to be executed when certain events happen. These events could include:

  • Detect a new Selected Element: You can subscribe to the 'selectedelement' event to be notified whenever a different element is selected in the Webflow designer. This is useful if you want to perform specific actions or updates based on the currently selected element. A null element signifies that no element is selected.
  • Detect a Breakpoint Change: Use the ‘mediaquery’ event to stay informed as the designer switches between breakpoints for desktops, tablets, or smartphones.
  • Detect a Page Change: The 'currentpage' event allows you to respond when the user switches to a different page in the Webflow designer. This can be handy if you want to load additional data or perform actions specific to the selected page.

Parameters:

  • event: ('selectedelement' | 'mediaquery' | 'currentpage') - The event type to subscribe to. You can choose from the following events:
  • callback: (Function) - A callback function that will be invoked when the subscribed event is triggered. The specific parameters passed to the callback depend on the event type.
    • breakpoint (BreakpointId): For mediaquery only - the BreakpointId represents the current media query breakpoint.

Returns: An Unsubscribe function that can be used to unsubscribe from the event and stop receiving notifications.

// Subscribe to changes in the selected element
const selectedElementCallback = (element) => {
  if (element) {
    console.log('Selected Element:', element);
  } else {
    console.log('No element is currently selected.');
  }
};

const unsubscribeSelectedElement = webflow.subscribe('selectedelement', selectedElementCallback);

// Subscribe to changes in the media query breakpoint
const mediaQueryCallback = (breakpoint) => {
  console.log('Media Query Breakpoint:', breakpoint);
};

const unsubscribeMediaQuery = webflow.subscribe('mediaquery', mediaQueryCallback);

// Subscribe to changes in the currently active page
const currentPageCallback = (page) => {
  console.log('Current Page:', page);
};

const unsubscribeCurrentPage = webflow.subscribe('currentpage', currentPageCallback);

Resize Window

This set of APIs allows a Designer Extension to set window size for an Extension. You can either select one of a list of predefined sizes : default (240x360), comfortable(320x460) and large(800x600) or you can set your own width and height ( min size: 240x360, max: 1200x800).

Window resizing should only be used for user actions needing specific window sizes ( e.g., Composing a Form may need a bigger than 'large' window size). Once this user action has been completed, please resize back to one of the predefined sizes listed above.

Set Extension Size

setExtensionSize(size: 'default' | 'comfortable' | 'large'): Promise<void>

Sets the extension size to one of predefined sizes. 

await webflow.setExtensionSize("large") ;
//Perform actions for large window

setExtensionSize(size: {width: number, height: number}): Promise<void>

Sets the extension size to the size specified in the call. If the specified size is larger than the user's viewport size, the extension will default to the width/height of the browser's viewport. 

await webflow.setExtensionSize({width: 1000, height: 700}) ;
//Perform actions for this window size

This is a high-level overview of the webflow object and its methods. For more detailed information about the specific objects and types (e.g., AnyElement, Style, StringElement, DOMElement), refer to their respective sections in this documentation.