Components

Webflow Components are customizable blocks created from Elements. They serve as the backbone for structuring visual hierarchies on a Webflow site, ensuring that designs are modular, reusable, and consistent.

A Card Component

Definitions

Also known as the component object, the component definition is the blueprint for a component. It defines the structure of elements within the component, as well as properties that can be used to customize the component instance. Any modifications made to the component definition will propagate to all associated component instances. This ensures consistency across instances while allowing for centralized changes.

A component instance is a “carbon-copy” of the component definition. While it retains the core design and structure of the definition, each instance can be customized through unique properties. This allows designers and users to assign custom values to a component instance’s properties, tailoring its appearance and behavior, without modifying the underlying component definition.

Component properties are pre-defined attributes within a Component Definition that can be assigned a specific value in the Component Instance. They allow designers or users to modify specific aspects of an Instance - text, images, links, and more - without affecting its foundational design.

Component Properties

Currently our APIs do not yet support the creation and management of Component Properties.

We understand the importance of this feature for our users, and we’re excited to share that it’s on our development roadmap. We’re committed to enhancing our API capabilities and will provide updates as we make progress. Thank you for your patience and understanding!

Component Operations

With Component concepts explained, here is a quick overview of the capabilities offered by the Components API:

Create a Component Definition

To create a component definition you’ll need a root element - or top-level element - that has child elements within its element hierarchy. With the root element identified, you can use webflow.registerComponent(rootElement) to register the component definition. In the above card component example, the root element would be the container DIV element, which has the img, div, and button as child elements.

1// Get selected element 
2const rootElement = await webflow.getSelectedElement();
3
4if (rootElement) {
5
6  // Create a component from the Root Element
7  const component = await webflow.registerComponent('MyCustomComponent', rootElement);
8  console.log(`Component registered with ID: ${component.id}`);
9
10} else {
11  console.log("No element is currently selected. Please select a root element first.");
12}

Edit a Component Definition

To make changes to a component definition, its component instance must be present on the page. You’ll then need to get the Component Instance, and use the enterComponent method to focus Webflow on the component definition. Once the component definition is in focused, you can get the root element of the component, and then insert / remove child elements from the root element.

1enterComponent: async () => {
2  // Step 1: Fetch the currently selected element
3  const selectedElement = await webflow.getSelectedElement()
4
5  if (selectedElement && selectedElement.type === 'ComponentInstance') {
6    //  Step 2: Enter the context of the selected ComponentElement
7    await webflow.enterComponent(selectedElement as ComponentElement)
8    console.log('Successfully entered the component context.')
9
10    // Step 3: After entering the component's context, fetch the root element
11    const rootElement = await webflow.getRootElement()
12    if (rootElement) {
13      // Check if element supports child elements
14      if (rootElement?.children) {
15        // Append newElement as a child to of the selected element
16        const newElement = await rootElement?.append(webflow.elementPresets.DivBlock)
17        console.log('Added new child element:', newElement)
18      } else {
19        console.log('Root element does not support child elements')
20      }
21    } else {
22      console.log('No root element found in this component context.')
23    }
24  } else {
25    console.log('The selected element is not a ComponentElement.')
26  }
27}

Add a Component Instance to a Page

Use webflow.createInstance(componentDefinition) to add a component instance to the page. Component instances can be nested as part of element hierarchies, including under other component instances.

Built with