⭐ Available in the following bundle: Code Bundle (incl. in Scale)
⭐ Available on the following plans: Business
👀 Not sure which plan you're on? Check your subscription here.
Heyflow is a no-code tool that allows you to build, design, and integrate your heyflows without the need to program. However, we allow you to write your custom JavaScript to expand Heyflow's functionalities.
💡 Want to use math.js? Our built-in calculation feature fully supports math.js syntax. When using functions, simply omit Math.—for example, instead of Math.min(x, y), use min(x, y) in your Heyflow formula. Learn more here.
How to add Custom JavaScript
To add custom JavaScript:
Go to the Build section of your flow.
Click on the Code Editor and JavaScript in the left-hand menu.
Use the editor to add your custom code.
Click on Save JS and publish your flow to set your edits live.
💡 Your script will be executed just before the heyflow loads.
🔎 If you want to react to navigation or submission events or run logic at specific points in the flow lifecycle, take a look at our Events API to get an overview of all possible events.
Requirements
In order to bring stability and ease of use to your custom JavaScript, it is required to use our official Flow API for manipulation of the flow. Other implementations are not supported by Heyflow.
The Flow API gives you controlled access to flow data and runtime behavior, such as:
Reading and updating input values
Changing visibility of blocks
Navigating the flow programmatically
Some custom methods for specific blocks
When a user interacts with a flow, a lot happens under the hood: blocks render, events are registered, third-party scripts run, and more. The Flow API hooks into these internals and gives you safe entry points to extend or react to this behavior — in ways the system expects.
If your use case involves reading or writing values, handling logic, or modifying flow behavior, the Flow API is the only supported way to do so.
❗ Direct DOM manipulation (e.g. using querySelector, setting innerHTML, injecting fields manually, etc.) is not supported. It may break at any time and won’t receive compatibility guarantees.
🔎 Learn more about the Flow API here.
Custom JavaScript in Heyflow Embeds
Be aware that if you have embedded your heyflow on a website, the JavaScript you write is executed in the global window context, not strictly within the heyflow. This means that your code is not automatically scoped to the flow, and special care must be taken to target it properly.
So if you’re using our Web Component embeds (<heyflow-embed>), your flow runs inside a shadow DOM. As a result, direct DOM queries, like document.querySelector(...), won't work unless they are properly scoped.
To ensure your script interacts with the flow correctly, you should wait for the heyflow-init event (see our Events API) and use that to access the shadow DOM safely.
let shadowRoot;
window.addEventListener('heyflow-init', (event) => {
shadowRoot =
(document.querySelector(`[flow-id="${event.detail.flowID}"]`) &&
document.querySelector(`[flow-id="${event.detail.flowID}"]`)
.shadowRoot) ||
document;
shadowRoot.querySelector('foobar').value = "baz";
})
❗Custom JavaScript in embedded flows only works if one flow is embedded per page. Multiple embedded flows may cause scripts to fail or behave unexpectedly.