Custom Code in the Builder Visual Editor
The Builder editor allows you to add event handlers, bind to state and even add custom JavaScript that will run on your page. This guide will walk through how to do things like access state properties, access events and even run custom JavaScript when your content loads.
State and actions
Builder allows you to bind state values to Builder blocks as well as add custom actions when the user interacts with your content. If you want to learn how to add state bindings or action handlers, check out our State and Action Guide.
When adding custom code in a state binding, note that you should not return a value. Instead, should use one of the following examples:
Data binding: one-line expressions
If you have a simple, one-line expression you can write it without a return statement in the code editor:
Data Binding: complex code blocks
If you have a more complicated code logic, you'll need to make sure you export a default value:
Accessing state
You can access Builder state in both state bindings and action handlers. State bindings will almost always be bound to Builder, but you can also modify the state value in the binding. For example:
Action handlers: using the Event object
Action handlers have an additional object you can access, event. This value is the HTML event emitted by the event you selected. You can use the event to access the target that emitted the event, or you can call methods like preventDefault or stopPropagation:
Editing custom JavaScript and CSS
Builder also allows you to add totally custom styles or JavaScript to your content by clicking the Edit Custom JS / CSS button on the bottom of the data tab:
This applies to the entire content entry, not a particular layer. Let's say you wanted to add a some custom styling to all builder text blocks for a particular page, you could add a rule like this to the Custom CSS panel:
You can also use the JavaScript panel to listen to run custom code on the page. Let's say you're rendering your Builder content lazily on the client and you want support linking directly to certain sections of a page based on the ID attribute of the section. You could do this with some custom JavaScript:
👉 Tip: As with any code you would add to your site, be cautious and thoughtful of the impact your custom code might have on performance and security. For example, If you are adding custom event listeners, make sure you use passive events.
Server side, client side, and async requests
You can run client side and/or server side using Builder.isBrowser and Builder.isServer. By default, any code not wrapped with Builder.isBrowser or Builder.isServer is run server side.
To run code client side, wrap it in if (Builder.isBrowser) {}
You also have access to fetch() on the client and server. For server side data you can export a default promise and it'll wait on that promise to resolve with any data before replying:
In the example above, the data will be saved on state and accessible in the server and client UIs as data bindings, etc. View our Advanced Data Guide for more information about fetching data and using it in Builder.
Accessing location data
You may have a situation where you want to access data form the URL. While you can easily access window.location in the browser, this doesn't really work if you're running in Node.js. To make easier for you to deal with URL data on all platforms, we've added a state.location object that you can access in custom code:
Up next
3rd party libraries
