Wondering what’s next for npm?Check out our public roadmap! »

    ouibounce
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/ouibounce package

    0.0.12 • Public • Published

    Ouibounce

    Originally created by Carl Sednaoui from MailCharts. Maintained and improved by generous contributors.

    tests twitter

    Ouibounce: A small library enabling you to display a modal before a user leaves your website.

    Quick note: Let me know if you end up using Ouibounce. I'd love to hear about your project / see Ouibounce in the wild :)

    The philosophy behind this project

    This library helps you increase landing page conversion rates. From my experience, you can expect a lift of 7% to 15% depending on your audience, traffic type (paid or unpaid) and copy.

    Talking about copy... please use Ouibounce to provide value to your visitors. With tools like these it's very easy to create something spammy-looking.

    Not sure what I mean by provide value? Here are a few ideas to get your creative juices flowing:

    Demo / Examples

    Modal inspiration

    I've designed a few modals just for you. Feel free to use these as inspiration.

    fancy with content fancy no header simple simple with book simple with feedback

    Installation

    You have a few options to choose from:

    • Download the minified or unminified script and include it on your page
    • Get Ouibounce from cdnjs.com
    • Use Bower: curl http://bower.herokuapp.com/packages/ouibounce
    • Use NPM: npm install ouibounce

    Note: Ouibounce is wrapped by a umd wrapper, so if you are using requirejs/amd or commonjs/browserify, it will still work fine.

    Usage

    1. Create a hidden modal
    2. Select the modal with vanilla JavaScript (or jQuery) and call ouibounce
    3. Optional: Save the function's return value to use the public API, allowing you to fire or disable Ouibounce on demand

    Example:

    ouibounce(document.getElementById('ouibounce-modal'));

    Example with jQuery:

    ouibounce($('#ouibounce-modal')[0]);

    Example using the public api:

    var modal = ouibounce(document.getElementById('ouibounce-modal'));
    modal.fire()

    Options

    Ouibounce offers a few options, such as:

    Sensitivity

    Ouibounce fires when the mouse cursor moves close to (or passes) the top of the viewport. You can define how far the mouse has to be before Ouibounce fires. The higher value, the more sensitive, and the more quickly the event will fire. Defaults to 20.

    Example:

    ouibounce(document.getElementById('ouibounce-modal'), { sensitivity: 40 });
    Aggressive mode

    By default, Ouibounce will only fire once for each visitor. When Ouibounce fires, a cookie is created to ensure a non obtrusive experience.

    There are cases, however, when you may want to be more aggressive (as in, you want the modal to be elegible to fire anytime the page is loaded/ reloaded). An example use-case might be on your paid landing pages. If you enable aggressive, the modal will fire any time the page is reloaded, for the same user.

    Example:

    ouibounce(document.getElementById('ouibounce-modal'), { aggressive: true });
    Set a min time before Ouibounce fires

    By default, Ouibounce won't fire in the first second to prevent false positives, as it's unlikely the user will be able to exit the page within less than a second. If you want to change the amount of time that firing is surpressed for, you can pass in a number of milliseconds to timer.

    Example:

    ouibounce(document.getElementById('ouibounce-modal'), { timer: 0 });
    Delay

    By default, Ouibounce will show the modal immediately. You could instead configure it to wait x milliseconds before showing the modal. If the user's mouse re-enters the body before delay ms have passed, the modal will not appear. This can be used to provide a "grace period" for visitors instead of immediately presenting the modal window.

    Example:

    // Wait 100 ms
    ouibounce(document.getElementById('ouibounce-modal'), { delay: 100 });
    Callback

    You can add a callback, which is a function that will run once Ouibounce has been triggered, by using the callback option.

    Example:

    ouibounce(document.getElementById('ouibounce-modal'), { callback: function() { console.log('Ouibounce fired!'); } });
    Cookie expiration

    Ouibounce sets a cookie by default to prevent the modal from appearing more than once per user. You can add a cookie expiration (in days) using cookieExpire to adjust the time period before the modal will appear again for a user. By default, the cookie will expire at the end of the session, which for most browsers is when the browser is closed entirely.

    Example:

    ouibounce(document.getElementById('ouibounce-modal'), { cookieExpire: 10 });
    Cookie domain

    Ouibounce sets a cookie by default to prevent the modal from appearing more than once per user. You can add a cookie domain using cookieDomain to specify the domain under which the cookie should work. By default, no extra domain information will be added. If you need a cookie to work also in your subdomain (like blog.example.com and example.com), then set a cookieDomain such as .example.com (notice the dot in front).

    Example:

    ouibounce(document.getElementById('ouibounce-modal'), { cookieDomain:
    '.example.com' });
    Cookie name

    You can specify cookie name passing cookieName: 'customCookieName'.

    Example:

    ouibounce(document.getElementById('ouibounce-modal'), { cookieName: 'customCookieName' });
    Sitewide cookie

    You can drop sitewide cookies by using passing sitewide: true.

    Example:

    ouibounce(document.getElementById('ouibounce-modal'), { sitewide: true });
    Chaining options

    The options are just javascript objects, you can therefore combine multiple options.

    Example:

    ouibounce(document.getElementById('ouibounce-modal'), {
      aggressive: true,
      sitewide: true,
      cookieDomain: '.example.com',
      timer: 0,
      callback: function() { console.log('ouibounce fired!'); }
    });

    Ouibounce API

    If you save the object returned by the ouibounce function, you get access to a small public API. Use this API to fire or disable Ouibounce on demand.

    Example:

    var modal = ouibounce(document.getElementById('ouibounce-modal'));
    modal.fire(); // fire the ouibounce event
    modal.disable() // disable ouibounce, it will not fire on page exit
    modal.disable({ cookieExpire: 50, sitewide: true }) // disable ouibounce sitewide for 50 days. 
    Disable options

    The disable function accepts a few options:

    Using Ouibounce with other libraries

    If you want to use this library with other plugins — such as Vex — you can call ouibounce with false. See #30 for discussion.

    var _ouibounce = ouibounce(false, {
      callback: function() { console.log('ouibounce fired!'); }
    });
    Twitter Bootstrap

    If you're trying to use Ouibounce with Twitter Bootstrap and are simply copying the example code I've included in the demo, you might run into some problems. See #66 to fix this.

    Legacy JS engines

    If you'd like Ouibounce to work in legacy JS engines (IE8 and below, for example), you'll need to add a shim such as es5-shim.

    WordPress

    Tomaž wrote a great tutorial on how to build your own WordPress opt-in form.

    Kevin Weber wrote wBounce, a WordPress plugin. I personally have not tested it, but have heard it works really well. Check it out.

    Miscellaneous

    Analytics

    Keywords

    none

    Install

    npm i ouibounce

    DownloadsWeekly Downloads

    2,750

    Version

    0.0.12

    License

    MIT

    Last publish

    Collaborators

    • avatar
    • avatar