a green background with white text

Developer-Friendly: Reduce, Reuse, Recycle

Extensions provide you with a flexible framework to build reusable components like announcements, special offers, carousels, lightboxes, and more. Extensions can be created using the visual editor or via the REST API.

Let’s say you have a travel website, you could use extensions to trigger a lightbox to prompt people to sign-up for your loyalty program after they complete a purchase. Using Optimizely Web Personalization, you could customize the messaging for the loyalty program based on your customer’s location. For instance, for cold weather travelers, you could promote “Save big on beach destinations” as part of the copy for the loyalty program. If you are still using Optimizely Classic and haven’t yet upgraded to Optimizely X, extensions are another compelling reason to do so.a screenshot of a computer

Example extension for displaying an email sign-up modal

Marketer-Friendly: Customize Infinitely

Extensions enable developers to build out a template in which they can expose a wide range of elements for marketers to customize such as text, imagery, call-to-action, background color and many more elements. Extensions are flexible and allow developers to specify input types from open-ended options such as freeform text to more constrained choices such as drop-downs, toggles, and color pickers. Instead of requiring developers to constantly create one-off code solutions, now extensions can be reused by non-technical teams anytime they have a similar promotion or use case.

graphical user interface, application

Some example input types available for extensions

Designer-Friendly: Stay on Brand

Another group that can benefit from extensions are designers. Extensions can be set up to allow certain elements to be highly customizable and other elements to be either hard-coded or restricted to a few pre-approved choices. For instance, you can allow free text entry but restrict the color of that text and background to certain pre-defined colors that are part of your company’s brand guidelines. That way you can run experiments and campaigns that don’t give your designer heartburn. In the example below, we created an extension that only allows three different color combinations for the banner background and allows the user to specify the placement of the call to action button.

Create Your First Extension

Creating an extension is easy. For any Optimizely X web project, follow the below steps:

  1. Go to Implementation > Extensions
  2. Define all of the fields that will have user entry. Each field will have a unique identifier that can be referenced in your code using {{extension.your_field_name}}
  3. Next add the custom HTML and CSS to your extension
  4. Under the ApplyJS section, you can customize where the extension gets injected into the page based on a specific selector.
  5. Finally, use the ResetJS section to clean up the extension. For instance if you click a button that forces a modal to appear and that button click also sets a cookie, then the resetJS can be used to remove that cookie + remove the modal.

Let’s walk through how to build an extension that allows someone to create a banner with customizable background color, headline text, and a call to action link. In the Optimizely extension creation UI, we can create the following elements: headline, call to action text, banner background color, and call to action link. The headline, call to action text, and call to action link will allow be presented by text fields but we’ll use a color picker for the background color. Each of these fields have their own corresponding API name that we will reference in our code. For instance, for the label Background Color, the API name is bg_color.

graphical user interface, text, application

Once we’ve set up the editable fields, we can easily reference them in our HTML code. We will reference these API fields using the syntax {{extension.api_name}}. In our HTML example below, we refer to the relevant API fields and add some CSS classes to style the extension. We’ve decided to make the font color of the text on the CTA button match the background color for consistency so we include the field extension.bg_color twice. The first time is to style the background of the banner and the second time is to style the font on the CTA button.

<div id="optimizely-extension-{{ extension.$instance }}" class="banner"><a href="{{extension.cta_link}}" class="cta_link"> {{extension.cta_text}}</a><div class="banner_text">{{ extension.text }}</div>

In our CSS section, we will add classes and styling for the banner, banner test, and CTA link. We choose to hardcode these values but we could also expose to our end users by making them into editable fields.

.banner {
    color: #555; 
.banner_text {
    color: white;
    font-weight: 400;
    text-align: center;
.cta_link {
    padding:5px 20px;

In our JavaScript section, we will specify that we want to insert our banner at the top of the page in the “elem.insertAdjacentHTML” section. However, we can inject the extension anywhere on our page or set up custom logic to trigger the extension only after a certain event occurs.

var utils = optimizely.get('utils');


 .then(function(elem) {

   // Prepend the extension html to the body

   elem.insertAdjacentHTML('afterbegin', extension.$html);


For more in-depth explanation of how to set up extensions, check out the extension docs. Extensions can also be created and updated using the REST API. For instance, you might have a number of extensions that are using a specific color and font scheme but your company decides to do a re-branding and now you need to update all of the colors and fonts. Using the REST API, you could iterate through and programmatically update all of the CSS to latest brand guidelines for your extensions.

Using Extensions

Extensions will show up in the “Create Change” section under Variations for experiments and personalization campaigns. You can add an extension to your experiment or campaign and customize the fields for your variation. For example, you can see the extension titled “Design Approved Banner” as an option.

a person holding a camera

Since extensions are deeply integrated with Optimizely’s experimentation and personalization platform, you can run experiments to test one of version of an extension vs. another version to see which one converts best.

Sharing is Caring

To help you get started using extensions, we’ve built a library of some useful extensions that you can download here on Github. Since, extensions are represented by a single json file, they are easy to share. To use one of the pre-built extensions, from the Extensions window click the button to Create New and then select “Using Json”. You can just copy and paste the json code from Github into this field.

graphical user interface, text, application

One example extension we built allows you to search for a hero image to customize your page. It uses the Unsplash API which provides you with access to thousands of free images for use. You can enter a keyword like “san fran” and it will return a hero image featuring San Francisco imagery for your site. You can download this extension from our GitHub repo here.

graphical user interface

If you you’ve built an extension that you are proud of and would like to share with the Optimizely community, reach out to us at developers@optimizely.com and we can add your extension to our library. We’re excited to see what you build!

Useful Resources:

Extensions Developer Docs

Extension Knowledge Base Article

Open-Source Extensions Templates on GitHub