Skip to main content

Everything you need to switch from Optimizely Classic to X in one place: See the Optimizely X Web Transition Guide.

Optimizely Knowledge Base

Use Optimizely with UI libraries like React and Vue

relevant products:
  • Optimizely X Web Experimentation
  • Optimizely X Web Personalization
  • Optimizely X Web Recommendations

  • Identify Optimizely solutions that will help you design and run experiments on React and Vue sites

The pursuit of better page speed and site performance means many organizations are moving to UI libraries like React and Vue. These architectural changes have many benefits, but they also create new challenges for experience optimization.

Experimentation on single-page applications (SPAs) in general is a little different than experimentation on static sites. This is tied to how Optimizely is activated, and Optimizely X answers these challenges very simply. Working with React and Vue creates a few more hurdles because of the many ways they can be applied. Each implementation has nuances that can make it difficult to identify the best way to run Optimizely experiments, especially if you’re not a developer! Using Optimizely on sites that use React or Vue will require developer involvement.

In Optimizely X, the powerful functionality of pages provides more granular control when delivering your experiences for React and Vue. If you aren't familiar with Optimizely's pages, reviewing these articles will make it easier to understand the concepts we're explaining here:

We're using React as an example in this article, but the principles we're explaining also apply to the Vue library.

Your stack combination

To understand the best way to use Optimizely with React, you need to understand the React stack combination that your site uses—and your development team can tell you which that is. Here are a few typical React implementations that we see regularly.


In a basic implementation, often referred to as "vanilla," you're using React only as a presentation layer (or "view"), enabling some of the performance and scalability you would expect with these UI libraries and some of the the newer efficiencies of building with ECMAScript 6 (ES6).

What React displays in the browser is dictated by the data that is instructing it at any time. A single “page” is likely to be made up of many different components that operate autonomously based on those instructions. Parts of components or even entire components may not be available to test until a specific trigger occurs. That means it’s important to identify a very specific trigger to activate Optimizely so that your experiment and its changes happen at the right time.


Isomorphic implementation means that all of your content and pages are built on your server in advance and passed to each visitor's browser on the first page load instead of being built in the browser like a static site. An isomorphic implementation improves site speed but often requires some pretty strict limits in terms of how the site elements are altered in a browser.

All browser-side A/B experimentation tools make changes in the browser as the page loads. In this scenario, a React site might break or try to reverse the change similarly to the enforced synchronization described below.

Enforced synchronization

All client-side web testing tools make their changes as your pages load on a browser. However, enforced synchronization of React won’t allow this. 

When the content that appears in a visitor's browser doesn’t match the content on your server, your server will enforce the original content and snap the page back to match the server. Think of this as the traditional flicker effect you would get from a poor tool implementation.

Optimizely toolkit solutions for React and Vue sites

Because React and Vue libraries are so flexible and can be used in many different ways, there is no ‘one-size-fits-all’ solution to the challenges of each implementation.

Instead of offering solutions like a proprietary framework, which requires developers to learn a new language and could create unnecessary challenges, we offer reusable, flexible options that developers can apply based on any scenario. This way, developers can complete one-time setup to activate React and Vue pages and components at the right time, which allows non-technical users to carry on experimenting.

Read on to learn about Optimizely's toolkit for React and Vue sites and find the best solution for your implementation.

Activate API

Optimizely X Web has an activate function that can be implemented to re-activate Optimizely whenever the URL changes:

Page activation modes

When creating pages or components, you can use a code interface for timing control and activate pages based on polling, manual API calls, or callbacks.

With libraries like React and Vue, you need to be quick with your changes to ensure that there is no interruption to visitor experience. The MutationObserver API is the best tool for that job.

The MutationObserver API helps Optimizely users and developers address page activation by providing another route to detecting changes in SPAs created with React or VUE. MutationObservers are just another way to watch and respond to changes that happen to elements on your pages.

Utility functions

The Optimizely X utility functions offer developers more granular timing controls. This is important because it lets you capture and apply your experiment changes at the correct point in your React app's generation.


Optimizely X extensions provide a template for writing reusable components and define a fill-in-the-blanks interface for customization. Extensions provide a flexible way to simplify technical challenges for non-technical people.

For example, imagine that your site has a carousel component written in React. Some of the elements might not be available on the page right away, but Marketing still wants to experiment on each section. In this case, developers can create an extension that allows Marketing to experiment on the carousel themselves as many times as they want, without having to go back to the technical team over and over again.

Learn more about extensions in our developer documentation.

Full Stack SDKs

Optimizely's Full Stack SDKs give developers the flexibility to run experiments anywhere in your code base. For example, React applications that render content server-side might do so using NodeJS, so Optimizely's Node SDK is a logical solution server-side. To ensure that the changes are duplicated on the browser, you would use the JavaScript SDK as a client-side solution.