Writing custom code in Optimize

Learn the building blocks for using the code editor and writing custom JavaScript or CSS.

Optimize supports most workflows without code — but when you need more control, you can write custom JavaScript or CSS. Whether you’re injecting new behavior, modifying content, or adjusting layout, the code tools give you full flexibility.

Where can you write custom code?

You can write JavaScript and CSS in several different contexts throughout Optimize:

Global code — add code (e.g., utility functions or shared styles) to every page where the snippet runs

Page definition code — define a custom rule in JavaScript to identify pages dynamically

Audience code — target visitors by writing JavaScript that evaluates user traits, behavior, or other conditions

Goal event code — track complex interactions by writing JavaScript that returns true when a conversion condition is met

Variation code — launch variations that leverage your custom JavaScript or CSS:

• Code-based variations — use the code editor to build a variation entirely from JavaScript and/or CSS. Ideal for changes the visual editor doesn't support — like running conditional logic or animating content.
• Code within visual editor variations — add JavaScript or CSS to a variation that starts in the visual editor. The code runs first, so you can prep the DOM or make changes before visual edits apply.
• Precondition code — if your variation contains custom code, it requires a precondition or selector. Write JavaScript that returns true or false to check for specific DOM states or user context before a variation can run.

About the code

• The JavaScript and CSS you write is transpiled — minified for performance, with console.log() stripped out
• CSS supports SCSS syntax, giving you flexibility with nesting and variables
• jQuery is not included by default — you can enable it via plugin

Writing code for variations

Whether you're creating a code-based variation from scratch or adding code to a visual editor variation, there are five key aspects of the code editor to understand:

• JavaScript field — write JavaScript to modify elements or behavior on the page
• CSS field — write CSS to adjust style attributes
• Selectors — identify elements on the page using CSS selectors
• Preconditions — use JavaScript to define when a variation should run
• Run code — preview how your code behaves in the live viewport

Selectors vs. preconditions

Both selectors and preconditions act as prerequisites for variations that use code. At least one is required when code is included. These are set at the optimization level and apply to every variation — even ones that don’t contain code.

Selectors tell Optimize which element(s) your code will modify. They enable anti-flicker protection — Optimize waits until the element appears before running the variation to prevent layout shifts or visual glitches.

Preconditions are JavaScript expressions that must return true before the variation runs. Use them when you need to check for multiple elements, specific values, or page state before applying the variation.

How to set selectors

If your variation updates multiple elements — e.g., an image, headline, and CTA — you’ll want to:

• Use a selector for the full container — to prevent flicker
• Use a precondition to check that all necessary elements exist

To set a selector in the code editor:

1. Select an element in the preview to lock in the selector in the Custom code panel
2. Click the Add selector icon in the Custom code panel to include additional elements

How to write preconditions

Preconditions are JavaScript expressions that must return true or false. “Truthy” values like 1 or 'hello' will throw an error and prevent the variation from running. All preconditions are evaluated line-by-line — if any fail, the variation won’t run.

To add a precondition in the code editor:

1. Click Add experience precondition in the Custom code panel
2. Enter your JavaScript expression in the Experience preconditions field

Examples:

• document.getElementById('heroImage') !== null — Checks that an image with ID heroImage exists
• document.querySelectorAll('.card').length === 4 — Checks for exactly four .card elements on the page