Utilities

User events & notifications

Listen for certain events based on a user’s behavior in the Webflow Designer, or notify a user of important events.

Notify a user

Send a notification to a user to alert them of important information and events.

Notifications will appear in the top right corner of the designer. Style notifications as either a success, error, or general information message. Notifications are helpful to let a user know that they have - or haven’t - completed a task successfully. Additionally, it’s helpful to let a user know about any unexpected errors your app may encounter.

To notify a user, use the webflow.notify() method.

Subscribe to an event

Additionally, you can subscribe to events in the designer using the subscribe method by subscribing to different event types. Including:

  • selectedelement: Listen for when a user selects an element on a page.
  • mediaquery: Get notified when a user changes breakpoints in the Designer.
  • currentpage: Get notified when a user navigates to a different page.
  • currentcmsitem: Triggers when a user selects a Collection page or a new item on a Collection page.
  • currentappmode: Detect when a user switches modes in the Designer.
  • pseudomode: Listen for changes to the pseudo-state of the Designer.

Using callbacks

Callback functions are used to handle and respond to events triggered by the Webflow Designer. Add your callback function as a parameter to the subscribe function to determine how to handle events in the designer. Here are some general tips for writing callbacks to handle events:

  • Keep them lightweight: Callbacks should be fast to execute to ensure a responsive user experience.
  • Error handling: Always include error handling in your callbacks to manage exceptions gracefully.
  • Unsubscribe when necessary: Remember to unsubscribe from events when your app no longer needs to listen to them, to prevent memory leaks and unnecessary processing.
1// Example of setting up and using callbacks for event subscriptions
2try {
3  // Store unsubscribe functions to clean up later
4  const unsubscribeFunctions = [];
5  
6  // Subscribe to element selection with error handling
7  // webflow.subscribe returns an unsubscribe function directly
8  const unsubscribeElement = webflow.subscribe('selectedElement', (element) => {
9    try {
10      // Process the selected element
11      if (element) {
12        const elementType = element.type;
13        const elementId = element.id;
14        
15        // Perform different actions based on element type
16        if (elementType === 'Image') {
17          // Handle image element selection
18          console.log(`Selected image element: ${elementId}`);
19        } else if (elementType === 'DOM') {
20          // Handle DOM element selection
21          console.log(`Selected DOM element: ${elementId}`);
22        }
23      }
24    } catch (error) {
25      console.error('Error in selectedElement callback:', error);
26    }
27  });
28  
29  // Add the unsubscribe function to our array
30  unsubscribeFunctions.push(unsubscribeElement);
31  
32  // Detect and respond to breakpoint changes
33  const unsubscribeBreakpoint = webflow.subscribe('mediaquery', (breakpoint) => {
34    try {
35      // Update UI based on breakpoint
36      if (breakpoint.name === 'xxl') {
37        // Handle xxl view
38      } else if (breakpoint.name === 'xl') {
39        // Handle xl view
40      } else if (breakpoint.name === 'large') {
41        // Handle large view
42      }
43    } catch (error) {
44      console.error('Error in mediaquery callback:', error);
45    }
46  });
47  
48  // Add the unsubscribe function to our array
49  unsubscribeFunctions.push(unsubscribeBreakpoint);
50  
51  // Cleanup function to unsubscribe when your app is done
52  function cleanupSubscriptions() {
53    // Call each unsubscribe function
54    unsubscribeFunctions.forEach(unsubscribe => {
55      if (typeof unsubscribe === 'function') {
56        unsubscribe();
57      }
58    });
59    console.log('Successfully unsubscribed from all events');
60  }
61  
62  // Call cleanup when your app is closing or switching modes
63  // For example: yourApp.on('beforeClose', cleanupSubscriptions);
64} catch (error) {
65  console.error('Error setting up event subscriptions:', error);
66  webflow.notify({
67    message: 'Failed to set up event monitoring',
68    type: 'error'
69  });
70}