The Visual Editor
The problem: testing ideas should not require a deploy
Section titled “The problem: testing ideas should not require a deploy”Marketing teams generate hypotheses faster than engineering teams can implement them. A headline change, a new hero image, a rearranged product grid — each idea is small, but scheduling it into a sprint creates a bottleneck that kills experimentation velocity. When testing a single copy change takes two weeks to ship, most hypotheses never get tested at all.
The visual editor removes that bottleneck. It lets you create experiment variations by pointing, clicking, and editing directly on your live page — no code, no deploy, no developer dependency.
How the visual editor works
Section titled “How the visual editor works”When you open a page in the visual editor, Optimizely loads your site inside an iframe and overlays an editing layer on top. This DOM overlay approach means you interact with your real page, not a simulation.
The editor generates a set of DOM mutations — instructions like “change the text of element X” or “hide element Y.” These mutations are stored in the experiment configuration and replayed by the snippet when a visitor enters the experiment.
Change types
Section titled “Change types”| Change type | What it does | How the snippet applies it |
|---|---|---|
| Text edit | Replaces text content in headings, paragraphs, buttons, labels | Sets innerHTML or textContent on the target element |
| Image swap | Replaces an image src with a new URL | Updates the src and srcset attributes |
| CSS modification | Changes colors, fonts, spacing, visibility | Applies inline styles or injects a <style> block |
| Element rearrange | Moves an element to a different position in the page | Detaches and re-inserts the DOM node |
| Hide / remove | Makes an element invisible or removes it entirely | Sets display: none or removes the node from the DOM |
| HTML insertion | Adds new markup to the page | Injects HTML at a specified position (before, after, or inside an element) |
| Redirect | Sends the visitor to a different URL entirely | Triggers a client-side navigation before the page renders |
Element selection
Section titled “Element selection”The editor identifies elements using CSS selectors. When you click on an element, Optimizely generates the most specific selector it can — typically combining tag name, class names, and position in the DOM tree. You can review and refine the selector manually if needed.
Fragile selectors are the most common cause of broken variations. If your site uses dynamically generated class names (common with CSS-in-JS frameworks like styled-components or CSS Modules), the selector may break on the next deploy. In these cases, add stable data-optly attributes to key elements or use the code editor instead.
Shadow DOM support
Section titled “Shadow DOM support”Modern web components use Shadow DOM to encapsulate their internal markup. The visual editor can interact with elements inside open Shadow DOM boundaries. Closed Shadow DOM roots are not accessible — changes to those elements require custom JavaScript in the code editor.
When the visual editor is not enough
Section titled “When the visual editor is not enough”The visual editor works well for content and style changes. It does not cover:
- Logic changes — Showing different content based on user state (e.g., logged-in vs. anonymous) requires code.
- Third-party widget modifications — Elements injected by external scripts after page load may not be present when the editor renders.
- Server-rendered personalization — If the content you want to test is generated server-side, client-side DOM manipulation creates flicker. Consider Feature Experimentation or Performance Edge instead.
- Single-page application transitions — In SPAs, the visual editor works on the initial page load. For route changes that do not trigger a full page reload, you need to use the Optimizely SPA support API or custom activation events.
For any change beyond the visual editor’s reach, the code editor (custom JavaScript and CSS) is available within the same experiment. You can mix visual and code changes in a single variation.
Best practices for reliable variations
Section titled “Best practices for reliable variations”A few habits prevent the most common issues with visual editor experiments:
- Use stable selectors. If your site generates random class names, add
data-optly-*attributes to elements you plan to test. These survive code deploys and framework re-renders. - Preview on multiple devices. The editor shows a desktop viewport by default. Always preview variations on mobile and tablet breakpoints before launch.
- Keep changes minimal. Each DOM mutation is a potential point of failure. Test one hypothesis per experiment rather than bundling unrelated changes.
- Check page load timing. If the element you are targeting loads asynchronously (e.g., a product recommendation widget), the snippet may apply changes before the element exists. Use custom activation events to delay variation application until the target element is in the DOM.
Decision guidance
Section titled “Decision guidance”| Scenario | Recommended approach |
|---|---|
| Headline or copy test on a marketing page | Visual editor |
| Button color or CTA placement change | Visual editor |
| Complete page redesign | Redirect test via visual editor |
| Checkout flow logic change | Code editor or Feature Experimentation |
| Mobile app experiment | Feature Experimentation SDK |
| Dynamic content behind authentication | Feature Experimentation SDK |
Start with the visual editor for speed. Graduate to the code editor when you hit its boundaries. Move to Feature Experimentation when the change lives in your application logic rather than the rendered page.
1. Your site uses a CSS-in-JS framework (styled-components) that generates random class names on each build. A marketer creates a visual editor experiment that works in preview but breaks after the next code deploy. What is the root cause and fix?
The visual editor identifies elements using CSS selectors. With CSS-in-JS frameworks, class names change on each build, breaking selectors. Adding stable data-optly attributes to key elements ensures selectors survive deploys.
The visual editor identifies elements using CSS selectors. With CSS-in-JS frameworks, class names change on each build, breaking selectors. Adding stable data-optly attributes to key elements ensures selectors survive deploys.
Review this topic →2. A marketer wants to test a different product recommendation widget on a product page. The widget is injected by a third-party script after page load. They try the visual editor but the widget does not appear. What should they do?
Third-party widget modifications are beyond the visual editor's reach because elements injected by external scripts after page load may not be present when the editor renders. The code editor with custom activation events lets you delay variation application until the target element exists in the DOM.
Third-party widget modifications are beyond the visual editor's reach because elements injected by external scripts after page load may not be present when the editor renders. The code editor with custom activation events lets you delay variation application until the target element exists in the DOM.
Review this topic →