How to add and customize a legacy popup

You will learn

Learn how to add and customize a legacy popup form for your website so you can encourage shoppers to subscribe to your brand, helping you grow your audience. 

If you'd like to add a popup to your site, Klaviyo offers a default modal form that you can customize. Here's what the default looks like:

Copy the popup form code

<script type="text/javascript" 

src="//www.klaviyo.com/media/js/public/klaviyo_subscribe.js"></script>

<script type="text/javascript">

KlaviyoSubscribe.attachModalSignUp({

 list: '[LIST ID]',
 
delay_seconds: 1,

 content: {
 clazz: ' klaviyo_modal',

 header: "Interested in our Newsletter?",

 subheader: "Stay in the know with news and promotions.",

 button: "Subscribe",
 success: "Thanks! Check your email for a confirmation.",

 styles: '.klaviyo_modal { font-family: "Helvetica Neue", Arial}.klaviyo_modal .klaviyo_header { color:#222;}.klaviyo_modal .klaviyo_subheader { color:#222;}.klaviyo_modal .klaviyo_submit_button,.klaviyo_modal .klaviyo_submit_button span { background-color:#0064CD; background-image: none; border-radius: 2px;}.klaviyo_modal .klaviyo_submit_button:hover,.klaviyo_modal .klaviyo_submit_button span:hover { background-color:#0064CD; background-image: none; }.klaviyo_modal .klaviyo_inner,.klaviyo_modal .klaviyo_fieldset .klaviyo_field_group input[type=text],.klaviyo_modal .klaviyo_fieldset .klaviyo_field_group input[type=email] { border-radius: 2px;}'

 }

});

</script>

After you've pasted the above snippet, you just need to update the LIST_ID placeholder to reference the ID of the Klaviyo List you'd like people added to when they subscribe. 

Popup custom configuration options

If you've used our default popup form code, there are different custom configuration options available, including:

• list: string, required. ID for the list that subscribers will be added to. Example, ABcDeF.
• pages: array, optional. Limits your form to show on these specific page paths for your website. If this isn't set and "excluded_pages" isn't set, the form will display on all pages. The asterisk(*) character can be used as a wildcard. Example: pages: ["/", "/products/*"]
• excluded_pages: array, optional. Excludes your form from showing on these specific page paths for your website. If you set this and don't set "pages", the form will appear on every page except for these. Example: excluded_pages: ["/cart", "/checkout"]
• delay_seconds: optional, float, default: 0.1. The delay, in seconds, before your form appears on the page.
• delay_num_pages: optional, int, default: 0. The delay, in number of pages, before your form appears on your website.
• has_closed_modal_cookie_name: optional, string. By default, when a user closes a flyout or popup, all flyouts and popups will remain closed on all pages. Use this option to give a flyout or popup a specific name, thus causing only others with the same name to remain closed.
• ignore_cookie: optional, bool, default: false. If a user closes a flyout or popup, all other flyouts and popups on your site will remain closed as the user continues to navigate the site. Set this option to true to force your flyouts and popups to always appear.
• extra_properties: optional, dictionary. Assign custom properties to someone's profile when the form submits. Example: If you want to track that someone is signing up from the form on your home page: extra_properties: { $source: 'HomePageSignUp' }
• success_url: optional, string. After a successful form submission, the page will redirect to this URL.
• success: optional, function. Set a custom function to run on a successful AJAX post.
• custom_success_message: boolean, default: false. If true, the success message for the form will be replaced with your success_message <div> if one exists, or the "success_message" option below.
• success_message: optional, string/HTML. The default Success Message for every form is, "Thanks for subscribing! Check your email for a confirmation message." If you would like to choose your own Success Message, leverage this configuration option.
• hide_form_on_success: boolean, default: false. If set to true, this will hide the form fields after a user submits the form.
• content: dictionary, optional, not available for custom built modal forms.
  • extra_fields: optional, array. Example: extra_fields: ["$first_name", "$last_name"]. Adds extra input fields to your form. Klaviyo will automatically assume these fields are text fields. If you want to specify a different type of field you can use an array of JSON data to create these fields with specified types.
  • clazz: optional, string. Assign a custom class to your form.
  • header: optional, string, default: "Interested in our newsletter?". Header message for your form.
  • subheader: optional, string, default: "Check your email for a confirmation message". Informational text under form header.
  • button: optional, string, default: "Subscribe". Text that displays on a form button.
  • success: optional, string/HTML, default: "<div>Thanks for subscribing!</div><div>Check your email for a confirmation message.</div>". Success message someone see's after updating their email.

Change a form's default content

If you've used the form code from Klaviyo's form builder, the first thing you'll want to customize is the default content of the form: the header, subheader, button text, and success message. You will find all of these in your form's "Content" array:

KlaviyoSubscribe.attachModalSignUp ({  
   list: 'LIST_ID',
   content: {  
      header: 'Want exclusive deals?',
      subheader: 'Be the first to know about special offers',
      button: 'Sign Up',  
      success: 'Thanks! Check your email for a confirmation.'  
   },  
   modal_content: false 
});

Make sure that if you customize the text here, you use the same syntax and don't delete or change the use of quotations, commas, or brackets.

Change when a popup is displayed

There are a number of options that allow you to control when the popup is displayed. The most common is changing the amount of time a browser stays on a page before your popup is shown.

To change the delay time before your popup appears on a page, set the delay_seconds option:

KlaviyoSubscribe.attachModalSignUp({
  ...
  delay_seconds: 15,
  ...
});

The delay_seconds option is counted in seconds and can be any positive number. If not set, the default value is to show the sign-up form immediately.

Styling your popup

If you'd like to change the default styling of your sign-up form (a more technical option) this the HTML structure of the sign up:

<div class="klaviyo_modal">
 <div class="klaviyo_inner">
 <a href="#" class="klaviyo_close_modal klaviyo_header_close">×</a>
 <form class="klaviyo_subscription_form">
      <p class="klaviyo_header"></p>
      <p class="klaviyo_subheader"></p>
      <div class="klaviyo_fieldset">
          <div class="klaviyo_field_group">
               <label>Email Address</label>
                <input type="email" name="email">
          </div>
      </div>
      <div class="klaviyo_form_actions">
          <button type="submit" class="klaviyo_submit_button"><span>Subscribe</span></button>
      </div>
 </form>
      <div class="success_message" ></div>
 </div>
</div>

You can then add your own HTML/CSS styling.

Add custom fields to a popup

Here is an example of customized popup code that adds "First Name" and "Last Name" fields.

As you can see, this leverages the extra_fields array within the content dictionary mentioned above. Be sure to swap out LIST_ID with your specific list's ID:

<script type="text/javascript" src="//www.klaviyo.com/media/js/public/klaviyo_subscribe.js"></script>
<script type="text/javascript">
  KlaviyoSubscribe.attachModalSignUp({
    list: 'LIST_ID',
    delay_seconds: 10.5,
    content: {
      clazz: ' klaviyo_modal_LIST_ID',
      header: 'Join our Newsletter!',
      subheader: 'Get the latest and greatest news from us.',
      button: 'Subscribe Me!',
      success: 'Thanks! Check your email for a confirmation.',
      extra_fields: ["$first_name", "$last_name"],
      styles: '.klaviyo_modal.klaviyo_modal_LIST_ID { font-family: "Helvetica Neue", Arial}.klaviyo_modal.klaviyo_modal_LIST_ID .klaviyo_header { color:#222;}.klaviyo_modal.klaviyo_modal_LIST_ID .klaviyo_subheader { color:#222;}.klaviyo_modal.klaviyo_modal_LIST_ID .klaviyo_submit_button,.klaviyo_modal.klaviyo_modal_LIST_ID .klaviyo_submit_button span { background-color:#0064cd; background-image: none; border-radius: 2px;}.klaviyo_modal.klaviyo_modal_LIST_ID .klaviyo_submit_button:hover,.klaviyo_modal.klaviyo_modal_LIST_ID .klaviyo_submit_button span:hover { background-color:#0064cd; background-image: none; }.klaviyo_modal.klaviyo_modal_LIST_ID .klaviyo_inner,.klaviyo_modal.klaviyo_modal_LIST_ID .klaviyo_fieldset .klaviyo_field_group input[type=text],.klaviyo_modal.klaviyo_modal_LIST_ID .klaviyo_fieldset .klaviyo_field_group input[type=email] { border-radius: 2px;}'
      }
    });
</script>

Create a completely custom popup

If you want more design control, you can write completely custom HTML and still have it interface with Klaviyo's JavaScript library. 

Start with our basic form code

To build your own popup, use the HTML below as a starting point, which contains Klaviyo classes to get the same look as a basic Klaviyo popup form:

<div class="klaviyo_modal" id="k_id_modal" style="display:none;">
   <div class="klaviyo_inner">
   <a href="#" class="klaviyo_close_modal klaviyo_header_close">×</a>
   <form action="//manage.kmail-lists.com/subscriptions/subscribe" method="POST" novalidate="novalidate" class="klaviyo_subscription_form">
      <input type="hidden" name="g" value="LIST_ID">
      <div class="klaviyo_fieldset">
        <p class="klaviyo_header">Interested in our Newsletter?</p>
        <p class="klaviyo_subheader">Stay in the know with news and promotions.</p>
      </div>
      <div class="klaviyo_fieldset">
      <div class="klaviyo_field_group">
        <label for="k_id_modal_$email">Email Address</label>
        <input type="email" id="k_id_modal_$email" name="email"></div>
      </div> 
      <div class="klaviyo_fine_print"></div>
      <div class="klaviyo_form_actions">
          <button type="submit" class="klaviyo_submit_button">
          <span>Subscribe</span>
          </button>
      </div>
      <div class="klaviyo_below_submit" ></div>
   </form>
   <div class="error_message" ></div>
   <div class="success_message" ></div>
   </div>
</div>

From here you can customize any of the HTML, keeping in mind a few things.

The <form> itself: The form with the class klaviyo_subscription_form should contain your sign up form and there are two required fields here:

• A hidden field with name="g" whose value is the list people will be subscribed to. 
• An input which includes name="email"

Hiding a closed popup: Any element with the class klaviyo_close_modal will exit the modal and permanently hide it from that visitor. You can use this on any buttons or icons that close the form.

The submit button: Use the class klaviyo_submit_button on the button that submits your form if you'd like it to be disabled while the form is submitting.

The success message: The element inside the klaviyo_modal wrapper with the success_message class will be shown after someone signs up if it exists.

Attach your custom popup to your website

Once you've edited your HTML, you'll need to let our JavaScript library know which element on your page represents your sign-up form. To do so, pass the CSS selector from your form to the attachToModalForm method along with any other configuration options you'd like to set on that form.

In this example, since our above form has an ID of k_id_modal you will have to use #k_id_modal as seen in the below JavaScript to attach Klaviyo's pop up code to your HTML element. You can add this code right below your form's HTML code on your website.

<script type="text/javascript" src="//www.klaviyo.com/media/js/public/klaviyo_subscribe.js"></script>
<script>
   KlaviyoSubscribe.attachToModalForm('#k_id_modal');
</script>

Add additional options to your popup

You can use the configuration options available to a Klaviyo popup form in your custom one. You can find a list of those in our popup options guide. For example, this attaches to a form with the id k_id_modal, shows on the home page and blog page, and displays after a 10 second delay:

KlaviyoSubscribe.attachToModalForm('#k_id_modal', {
  pages: ['/', '/blog*'],
  delay_seconds: 10,
});

There is an additional success option you can set, which should be a function to call when the form is successfully submitted. If set, that method will receive a single argument, which is a jQuery wrapper around the form element that was submitted. This can be useful if you show or hide parts of your custom popup once the form is submitted:

KlaviyoSubscribe.attachToModalForm('#k_id_modal', {
  ...
  success: function ($form) {
  $form.find('.hide_on_submit').hide();
  },
  ...
});

Add an image to a custom popup

To add an image to the top of your popup, consider the following example:

The code:

<div class="klaviyo_fieldset">
 <img style="display:block;margin:0 auto;margin-bottom:8px" src="https://cdn.shopify.com/s/files/1/1057/2060/t/2/assets/logo.png?14435604036577717484" alt="Thank you for signing up">
 <p class="klaviyo_header">Welcome to Candy Corner!</p>
</div>

This <img> input is placed directly above the Klaviyo Header input, where:

• style = any in-line CSS styling you would like to apply to your image
• src = the URL link to your image (image must be hosted online already)
• alt = the text you would like to show if the image does not appear

Additional resources

• Legacy sign-up forms vs. built-in sign-up forms reference
• How to trigger a legacy popup when a button is clicked
• How to add custom fields to a legacy form