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.
👉 Tip: To add custom HTML to your page use the Custom Code Block instead.
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 JS code in a state binding or action handler, note that you do not need to use the return keyword to return a value. Instead, should use one of the following four 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 more complicated 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:
Custom CSS
In the Custom CSS panel you can write CSS rules to style elements in your content entry. For example, you can use class selectors to define styles for classes.
Then to add a class to a Builder block, select the block or layer and scroll to to the bottom of the Style tab. Add the class name(s) to the Advanced section.
Custom Javascript
You can run JS 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 on Builder's servers.
To run code client side, wrap it in if (Builder.isBrowser) {}. 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:
You also have access to fetch() on the client and server. For server side data you can export a default promise and it will 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.
👉 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.
Up next
3rd party libraries
Looking to hire a 3rd party to help with your project?
Submit a project request and our partnerships team will reach out to connect you with an Expert from our partner ecosystem.