Using the visual editor

In this article:

The visual editor interface

Before creating your first Optimize variant, you should familiarize yourself with the visual editor. It consists of two main components, the app bar and the editor palette, which are described below.

The app bar

The app bar is a navigation bar that appears across the top of your page when creating a variant. The app bar is divided into two sections, the upper section contains the experiment name and status, the variant name, preview, change list, diagnostics, and help. The lower section contains the element selector, the CSS path and buttons for the CSS editor, interactive mode, and move settings.

Each of the app bar settings are described in more detail in the Introducing the visual editor article.

The editor palette

The editor palette appears on the lower right of the page and contains editing controls for the currently selected element. In the blue bar are buttons for undo, redo and close ("x"). Click the EDIT ELEMENT button to edit its text, HTML, or add a piece of JavaScript that runs when it loads. The lower portion of the palette contains controls for the current selection. For example, when a text element is selected, you can edit its dimensions, location, typography, background, border, and layout.

Learn more about all the tools in the app bar and editor palette in the Introducing the visual editor article.

Using the CSS code editor

In addition to making style changes in the Optimize visual editor, you can also use the CSS code editor to view and edit CSS style changes in your variant. Edits made in the CSS code editor are translated into Optimize style changes when saved. Text, HTML, and other non-CSS style changes (e.g. element style) are not visible and will not be affected by the CSS code editor.

To access the CSS code editor, click the embed button (“Embed”) in the lower-right section of the app bar.

This will bring up the Optimize CSS code editor:

Optimize CSS code editor screenshot.

Support for conditionals

The CSS code editor supports conditionals, like media queries, making it easy to implement a variant for a responsive page. For example, you can decrease a font size to 14px on screens that are less than 500px by adding the following CSS code:

@media(max-width: 500px) {
  body {
     font-size: 14px;

Advanced CSS code editor

If you’re comfortable with CSS, you can implement your variant entirely in the CSS code editor. CSS added here is translated into individual style changes that are visible in the change list.

Similarly, you can implement a leading variant by copying code from the CSS code editor and deploying it on your production website.

Responsive visual editor

The Optimize visual editor allows you to ensure that your variant is compatible with multiple screen sizes and device types. It also lets you make responsive style changes that apply to specific screen widths.

There are two ways ways to do this:

  1. Choose one of the predefined devices in the device menu, at the top of the visual editor: Use this option when you want to test your variant on a specific device model. This option will simulate the corresponding browser user agent and is best suited if you have a dedicated mobile version of your site.
  2. Choose Responsive from the bottom of the device menu, then use one of the responsive preview methods (below) to simulate different screen sizes. Use this option if you have a responsive site that dynamically adjusts to the width and height of the browser screen – even on a desktop web browser. With this option you may also make responsive style changes using the visual editor.

Editor: Device menu screenshot

The visual editor's device menu.

Responsive previewing

When you select Responsive from the device menu there are three ways to preview your variant in different screen sizes:

  1. Click in the gray auto-width bar located immediately below the element selector, to simulate predefined page widths (e.g. 320, 400, or 600px). Note: this only changes the width, not the height. If your site is already using responsive CSS, the bar will use your most common width breakpoints, allowing you to easily identify all the different ways that your pages look.
  2. Enter values directly in the page sizer, located below the auto-width bar, for your desired width and height (in pixels), then press RETURN.
  3. Drag the dark gray resize handles on the right and bottom edge of your variant to simulate a specific screen size to see how your variant responds. This is similar to how your variant will render when a user dynamically changes the size of their browser window.


The visual editor's responsive preview options.

Responsive editing

In addition to previewing your variants, selecting Responsive from the bottom of the device menu allows you to make responsive style changes via the breakpoint menu.


Device menu (left) and breakpoint menu (right).

The breakpoint menu contains options for the most common simple responsive (i.e. media query) restrictions that apply to your site (for width only). If your site is already using responsive CSS, the bar will use your most common width breakpoints and will let you make changes that are consistent with your current breakpoints.

Editor breakpoint menu screenshot

The expanded breakpoint menu.


When you select an option from the breakpoint menu, the editor will enter a special state where all style changes using the editor palette will use this restriction. For example, if you select "Up to 600 pixels wide" from the breakpoint menu, then change the font size used by a button, the button will use the original font on devices or browser windows greater than 600 pixels wide. This will be highlighted in the editor palette. This effect applies only to style changes and will not affect text or content changes.

Editor palette constrained by the breakpoint menu.

The editor palette constrained by values selected in the breakpoint menu.

When using the breakpoint menu, responsive resizing with the resize handles will still work while dragging (to help you preview), but the page size will return to the selected breakpoint width automatically.

You can see and change the media query of each individual style change using the change list or the CSS code editor and you can also use them to specify more complex media query restrictions. You can exit responsive editing mode by selecting All sizes at the top of the breakpoint menu.

Change list

As you make changes in the visual editor a change list is produced. Think of the change list as a set of primitive instructions that transform the original page into the variant that you wish to test. The number of changes in the current variant is noted in the app bar (e.g. – "1 change" in the screenshot above.) To review the change list, click on the number of changes in the app bar.

Optimize does not load or use an external library to implement changes. Instead, it implements the change instructions in the form of compact Google Tag Manager tags.

Change types

Optimize supports the following change types:

Style change

Used to implement style attribute changes, including element size and position.

Style change allows you to implement the instruction using a CSS rule:

#target { color : red }

...or use the target element’s style attribute:

<p id="target" style="color : red"> </p>

The visual editor defaults to the most correct syntax, favoring the CSS Rule approach.

If there is a more specific CSS rule in the page that overrides the new rule, the visual editor will use the "important" property, e.g.:

#target { color : red !important}

The editor will only use the element's style if the above rule is also overridden by a more specific rule on the page.

The CSS Rule approach minimizes flicker (caused when unstyled content appears briefly before the CSS loads). In contrast, changing a style property using requires that the element already exist on the page, thereby increasing the chance that it will be briefly visible to the user before it is changed.

You can examine the options that the editor picked, and modify any of them by editing an existing Style change.

Advanced editor – Edit style dialog screenshot

Attribute change

Used to implement element attribute changes, such as the target of a link, or the source of an image. You can examine and modify properties, such as the CSS selector, attribute and value.

Advanced editor – edit attribute screenshot

Text change

Used when you make inline text edits in the editor. When an element contains text interleaved with child elements, the editor indicates the part of the text that was modified. In the following example, you can only change one of the parts, e.g. "Some text." To edit, click each part individually, or tab to move to the next part.

Some text 
<b> a child element </b>
Some other text


The following modes are supported:

  1. Replace: Replaces an existing text part.
  2. Insert: Inserts a new text part inside the target element, at the beginning.
  3. Append: Inserts a new text part inside the target element, at the end.
  4. Before: Inserts a new text part before the target element.
  5. After: Inserts a new text part after the target element.

Advanced editor - edit text screenshot

A Text change is safer and less invasive than an HTML change. It is preferred when only the text is modified. A Text change does not have side-effects in document structure (and CSS selectors or other elements) and does not affect event handlers that may be registered in the target elements.

HTML change

Used to replace or insert new HTML. The following modes are supported:

  • Replace: Replaces the existing HTML content
  • Insert: Inserts new HTML content inside the target element, at the beginning.
  • Append: Inserts new HTML content inside the target element, at the end.
  • Before: Inserts new HTML content before the target element.
  • After: Inserts new HTML content after the target element.

Advanced editor – Insert text before screenshot

An HTML change will result in the loss of all non-inline event handlers. For example, this button will stop working after an HTML change (e.g. Insert HTML before):
<button id=”button”> My button </button>
    .addEventListener("click", function() {alert(‘hello’);});

HTML changes happen after the initial HTML content has been parsed by the browser, so any scripts that it contains will have already been executed. For this reason, the visual editor removes script tags when loading the HTML content for editing. You cannot include scripts in new HTML content. To run a new script as part of a variant, use a Script change (Run Javascript). You cannot modify existing scripts.

Reorder change

Two approaches are supported for dragging and moving an element to a different location on the page. The default approach produces a Reorder change, which changes the placement of the element in the DOM. The element will have a new parent and/or sibling element(s). This typically results in the element adopting the style of the elements in its new area.

Use a Reorder change when reordering menu items, or other similar looking elements.

A Reorder change involves a source and a target CSS selector which can be changed from the related dialog as well as a Move mode:

  • Top: Makes the source element be the first child of the target element.
  • Bottom: Makes the source element be the last child of the target element.
  • Before: Makes the source element be the previous sibling of the target element.
  • After: Makes the source element be the next sibling of the target element.

Script change

A Script change allows Optimize to run arbitrary JavaScript on every element that matches a CSS selector. The change allows Optimize to run the JavaScript as the body of a function that takes the element as a parameter.

You can also use "head" or "body" for the CSS selector and run the JavaScript just once (since there is only a single such element in the page). The selector you use, in combination with its "run at" option, affects the preconditions that determine when the script will run. Read When change instructions are applied, below.

If a CSS selector matches multiple elements, the provided script will run multiple times, once for each element. On each call, the element is passed as the single argument of the function.

Each call takes place as early as possible based on the selected option:

  • After opening tag: Only the opening tag of the matched element needs to have been parsed and available in the page in order for the script to run.
  • After closing tag: All contents and the closing tag of the matched element must have been parsed and available in the page in order for the script to run.

For example:

  • Using the "After opening tag" option with selector "head" means that the script change can run as early as when the Optimize snippet is first executed in the <HEAD> (synchronous blocking execution).
  • Using the "After closing tag" option with selector "body" means that the script change will run after the document ready (DOMContentLoaded) event.

Advanced editor – Run JavaScript screenshot

Multiple target elements

As with other change types, a Reorder change allows you to modify its source and target CSS selectors to match multiple elements. For example, by selecting multiple source elements, you can move all items of a menu into a different menu.

A Reorder change also supports a target selector that matches multiple elements. This can be used to change the order of two table columns or any other tabular structure in the page.

  • If there are more targets than source elements, the additional target elements are ignored.
  • If there are more sources than target elements, the additional source elements are added in the last target element.

Move anywhere

There is an alternative approach for moving elements to a different location. Enable the Move anywhere option, in Move settings.

Optimize editor – Move anywhere switch

Using this approach results in position related style changes (i.e. left, top, position etc). The element remains in its same location in the DOM, but appears to be moved to a new position. Typically, its style remains unaffected and there is no change to the rest of the page.

Use Move anywhere when changing the position of global buttons or areas (such as a login area) and already-positioned elements.

Automatically select for reorder

This option is on by default, so that it’s easy to pick the correct source and target elements while dragging. The editor picks the correct element (e.g.: a list item <li> instead of the image <img> it contains) and confines reordering to what's inside the container (i.e. the list element <ul>).

You can disable this option to reorder any element to any other place in the DOM. You can also change the default Move mode from Before/After to Top/Bottom, by unchecking Reorder outside target element.

CSS selector building

When you click on a page area, the editor selects the deepest element in the clicked area.

Use the hierarchy bar to select any ancestor element (which may occupy the same area and may affect visible properties of that area, such as the background image or color). Hover over the ancestor elements in the hierarchy bar to inspect the area that each element occupies. Click and select the element, and use the editor palette to inspect the properties it affects.

Advanced editor – CSS selector screenshot

Once an element has been selected for change, a significant property of that change is the CSS selector that the editor builds, since it can help match the correct elements.

Here is the algorithm that the editor uses to build the selector:

  • Traverse up the ancestors in the DOM until there is one that can be uniquely identified
    • By its ID attribute
    • By a class used only by that element in the page
    • As the document <BODY>
  • Go back downwards to the selected element and:
    • Use the tag name if there is only one child element with that tag
    • Use the :nth-of-type selector if not
Tips for CSS selectors
  • It’s always preferable to target elements with an ID or unique class or a close ancestor that has them. This makes your variants easier to maintain when there are small changes in the page structure.
  • When using classes as unique identifiers, make sure that you use a representative page as your editor page (and not, for example, a product results page with just a single product).
  • You can always modify the CSS selector of a change and type in your own selector. The editor will highlight the newly matched element/elements.
  • You can disable the options of using ID or a unique class for trimming a selector hierarchy. This can be useful if these attributes use a CMS or database identifier and vary.

When change instructions are applied

The Optimize snippet is loaded in the page <HEAD>. This means that when the change instructions run, the target elements have not been parsed and are not available in the page.

Many pages include synchronous scripts in the body that delay the DOM being ready. To avoid flicker, Optimize changes monitor the document every 80msec until matching elements can be identified. If a CSS selector matches multiple elements on a complex page with multiple synchronous scripts, the change can be applied progressively on multiple iterations, as matching elements get parsed.

Different change types are also applied at different phases of the parsing. Text, HTML and Reorder changes are applied only when all contents and the closing tag of the matched element have been parsed. Attribute and Style changes require only the opening tag, and Script changes are configurable by the user.

As a further step to minimize flicker, Optimize temporarily hides matched elements (using <STYLE> tags which are added very early) until the elements are matched and changes are applied.

  • These details may be significant if your changes involve a global container or the document body.
  • Style changes implemented as CSS rules are added synchronously in the <HEAD> when the Optimize snippet runs, and don’t have to wait for matched elements to be parsed.

Order in which changes are applied

The order of change instructions is respected when there are side-effects (such as a later change modifying an element that was added by an earlier change). But Optimize may apply changes in a different order when there are no side-effects and matching elements of a later change become available. Optimize may even run changes matching multiple elements progressively and in parallel.

Although Optimize includes these features, it’s preferable to edit the document starting from top and moving downwards.

Activation events

Dynamic pages and single page web apps typically load additional data after the page has finished its initial load. Optimize supports these implementations via a feature called Activation events. Learn more about Activation events.

Was this article helpful?
How can we improve it?