How to Master GSAP Interactions in Webflow — Lesson 7

In this comprehensive lesson from the Mastering GSAP Interactions course, developers are guided through the exact process of building a highly professional, fully persistent light and dark mode switch inside Webflow. The core value of this tutorial lies not just in creating a visual toggle, but in architecting a scalable and maintainable color system from the ground up. By moving beyond amateur animation techniques, viewers will learn how to implement a production-ready system that integrates custom CSS, Webflow variables, and native GSAP logic to control global theme states cleanly and efficiently.

The technical approach focuses on leveraging Webflow’s manual variable modes alongside GSAP’s set action. Rather than animating individual color properties—which creates bloated code and interaction conflicts—viewers will discover how to toggle a single master class to completely shift the site's theme. Furthermore, the lesson introduces an elegant custom CSS workaround that applies smooth, 800-millisecond color transitions strictly during the theme switch, immediately removing them afterward to preserve the integrity of other hover and scroll interactions.

Ultimately, this video ensures the viewer achieves a flawless, enterprise-grade user experience by integrating vanilla JavaScript and local storage. Viewers will learn how to save a user's theme preference across page reloads and site navigation, while automatically respecting system-level color preferences. Crucially, by shifting the execution to the head code and targeting the root HTML element, the resulting solution completely eliminates the dreaded "white flash" or flickering effect upon page load, leaving the viewer with a robust, highly reusable system for any future project.

• Systematize Colors with Variable Modes: Before building any logic, establish a foundational color system using Webflow variables. By creating a "Base" (light) mode and a manual "Dark mode," you can map essential colors globally (like to the body tag), enabling a site-wide shift with just a single class change.
• Optimize Performance with GSAP’s Set Action: Instead of using traditional animation properties that manually transition colors, utilize GSAP's set action. Combined with a toggle play reverse control, this instantly adds or removes a master dark-mode class, making state management drastically cleaner.
• Isolate Smooth Transitions via Custom CSS: To prevent theme transitions from interfering with standard hover or scroll animations, temporarily inject a custom CSS class (.theme-transition *). GSAP applies this class precisely when the toggle is clicked and removes it immediately after the 800ms transition finishes.
• Ensure True Persistence via Local Storage: Utilize a lightweight footer script to save the user's active theme into the browser's localStorage. This guarantees the selected theme persists entirely across different pages, new tabs, and browser reloads without relying on easily-cleared session data.
• Eliminate Page Load Flickering: To create a seamless experience that respects the user's operating system preferences, move the target state from the body to the root html element. Placing the retrieval script inside the custom head code guarantees the correct theme is evaluated and applied before the browser visually renders the page, completely avoiding a flashed light mode.

• 2:23 - Define a new variable collection in the variables panel (e.g., "colors") to serve as the foundational color system.
• 3:20 - Create a new color variable and assign it to a dedicated group by prefixing the name (e.g., group/variable).
• 4:32 - Create a new "manual" variable mode to define the specific color values for the dark mode state.
• 6:14 - Select the 'body (all pages)' tag and assign the newly created color variables to its global font and background properties.
• 10:13 - Set the GSAP interaction control type to "toggle play reverse" so the animation plays forward and reverses on alternating clicks.
• 10:51 - Set the "runs on" property to "all pages" inside the interaction settings to ensure the toggle works globally across the project.
• 15:40 - Use the GSAP 'set' action to instantly toggle the dark-mode class on the target element.
• 16:09 - Type dark-mode in the style selector input and attach the newly created "dark mode" manual variable mode to this class.
• 19:05 - Paste custom CSS into the site settings <head> code to isolate smooth color transitions (using an 800ms duration) to a dedicated theme-transition utility class.
• 22:04 - Add a GSAP 'set' action at the beginning of the timeline (0 seconds) to apply the theme-transition class to the body.
• 23:04 - Add a second GSAP 'set' action at the end of the timeline (0.8 seconds) to remove the theme-transition class, preventing conflicts with other page animations.
• 24:48 - Change the target of the 'toggle dark mode' interaction from the body element to the root HTML element to prepare for the anti-flickering script.
• 25:18 - Inject JavaScript into the site settings' head and footer code to retrieve/save the user's theme in localStorage and check their system-level color preferences.
• 28:37 - Convert the fully configured mode toggle element into a component so it can be deployed across all pages of the site easily.

Building a Persistent Dark Mode Toggle in Webflow with GSAP

This guide provides a step-by-step technical walkthrough for architecting a scalable, persistent dark mode system in Webflow. The process utilizes Webflow's manual variable modes, GSAP interactions, custom CSS, and vanilla JavaScript to deliver a flawless, enterprise-grade user experience.

Step 1: Define a Foundational Color System

• Timestamp: 2:23 - 4:12
• How: Open the Variables panel and create a new collection (e.g., "Colors"). Begin defining your base (light mode) color variables. Organize them into logical groups by prefixing their names (e.g., background/primary or font/secondary).
• Why: Organizing your variables into groups creates a logical foundation for the project. This setup must be done correctly upfront so that switching between themes later requires minimal effort.

Step 2: Create a Manual "Dark Mode" Variable Mode

• Timestamp: 4:32 - 5:16
• How: In the Variables panel, click "New mode", name it "Dark Mode", and select the "Manual" type. Proceed to manually overwrite the base inherited colors with your new dark theme values.
• Why: Selecting a "Manual" variable mode (instead of Automatic) allows you to control the theme shift explicitly via the Style panel using a custom class, rather than relying strictly on native browser breakpoints.

Step 3: Assign Global Variables to the Body

• Timestamp: 6:14 - 6:55
• How: Select the body (all pages) tag in the Style panel. Assign your newly created global variables to its core properties, such as font color and background color. Proceed to link your variables to all other specific elements and interactive states throughout the site.
• Why: Because most standard HTML elements inherit basic styling from the body tag, applying variables here globally ensures a consistent baseline and saves significant development time.

Step 4: Structure the Toggle UI

• Timestamp: 7:07 - 9:35
• How: Build a fixed toggle button (e.g., a .mode-toggle wrapper) containing an inner .mode-toggle-switch div. Link the background and border colors of both elements directly to your variable system.
• Why: Linking the toggle's styles to your variables guarantees that the UI element itself will seamlessly update its appearance based on the active theme state.

Step 5: Configure the Primary GSAP Animation

• Timestamp: 10:13 - 11:45
• How: Select your toggle wrapper and add a GSAP click interaction. Set the control type to "Toggle play reverse" and ensure the "Runs on" property is set to "All pages". Create an action to animate the inner switch element moving along the x-axis.
• Why: "Toggle play reverse" allows the same interaction to animate forward upon the first click and reverse upon the next, creating a smooth back-and-forth experience. Setting it to run on all pages ensures the component functions globally.

Step 6: Use GSAP's "Set" Action to Switch Themes

• Timestamp: 11:52 - 17:05
• How: Create a second click interaction on the toggle (also using "Toggle play reverse"). Instead of an animation, use a GSAP "Set" action. Target the body (we will change this to HTML later), choose the "Class" property, input a custom class named dark-mode, and set the action type to "Toggle". Finally, go to your Style Guide page, apply the dark-mode class to a dummy div, and attach your manual "Dark mode" variable mode to it.
• Why: The GSAP "Set" action instantly applies or removes a class without a duration or easing. By attaching your manual variable mode to a single class, toggling this class instantly forces the entire site's color palette to shift. Keeping a dummy div in the Style Guide prevents Webflow from accidentally deleting it during a class cleanup.

Step 7: Isolate Smooth Transitions via Custom CSS

• Timestamp: 18:58 - 21:21
• How: Go to Site Settings > Custom Code > Head Code. Paste custom CSS targeting a new .theme-transition * class (including pseudo-elements). Apply a smooth 800ms transition specifically to properties like color, background-color, and border-color. Create a dummy div in the Style Guide with this class so Webflow recognizes it.
• Why: Placing it in Site Settings ensures the CSS is injected globally. By isolating the transition to a specific utility class, you prevent standard CSS transitions from permanently interfering with complex hover, click, or scroll animations across the site.

Step 8: Integrate Smooth Transitions into the Timeline

• Timestamp: 22:04 - 23:22
• How: Reopen your first interaction (the switch animation). Add a "Set" action at exactly 0 seconds to toggle ON the theme-transition class on the body. Duplicate this action, move it to 0.8 seconds (the end of the timeline), and toggle the class OFF.
• Why: This temporarily activates smooth CSS transitions exactly when the theme is changing, and removes them the millisecond the shift is finished. It ensures a clean visual transition without polluting global elements.

Step 9: Target the HTML Element to Prevent Flickering

• Timestamp: 24:41 - 25:13
• How: Return to your "Set dark mode" interaction. Update the target of the dark-mode class toggle action from the body element to the root HTML element.
• Why: The root HTML element is loaded and parsed before the body renders. Shifting the target prepares the site for the upcoming JavaScript sequence, which requires early access to the DOM to prevent page-load flickering.

Step 10: Implement Local Storage for Persistence

• Timestamp: 25:18 - 28:09
• How: In Site Settings, inject two scripts. In the Head Code, add a script that checks localStorage and the user's OS system preferences, applying the dark-mode class directly to the HTML element if necessary. In the Footer Code, add a script that listens for clicks on the toggle and updates localStorage with the newly selected theme.
• Why: localStorage is used because it saves the user's preference permanently across closed tabs, page navigation, and reloads. The Head script must run before the page renders to avoid the dreaded "white flash", while the Footer script accurately saves the state after the user interacts with the loaded DOM.

Step 11: Componentize the Toggle for Deployment

• Timestamp: 28:30 - 28:43
• How: Back in the Webflow designer, right-click the outer .mode-toggle wrapper and convert it into a reusable Component. Paste this component onto all active pages.
• Why: Converting the toggle into a component guarantees that the interactions, logic, and styling are perfectly synchronized everywhere it is used on the site.

To build a dark mode toggle with GSAP, define a manual "Dark mode" variable mode within your Webflow color system. Use a GSAP "set" action triggered by a toggle button to instantly add or remove a master "dark-mode" class on the root HTML element. This approach cleanly shifts the global color palette without the need to manually animate individual CSS properties.

To prevent CSS color transitions from conflicting with page interactions like hover or scroll effects, isolate the transition styling. Use a GSAP sequence to temporarily add a custom CSS transition class to the body exactly when the theme toggle is clicked, and automatically remove it 800 milliseconds later once the visual shift is complete.

Use a custom JavaScript snippet in your site's footer to save the active theme state into the browser's localStorage whenever the toggle is clicked. Unlike standard session storage, localStorage ensures the chosen theme persists flawlessly across internal page navigation, browser reloads, and even closed tabs.

Prevent the white flash effect by placing a JavaScript theme-checking script directly inside your site's <head> code. By targeting the root <html> element rather than the <body> tag, the script applies the saved dark mode class immediately before the browser begins visually rendering the page.