Demo

Basic Generated Close Button Fade Scroll-lock Fade & scale Active Bg Absolute Tooltip

Features

  • Positioned with CSS: Overlays are horizontally and vertically centered with CSS, without any JavaScript offset calculations, therefore remain centered even if their height change.
  • Suitable for responsive web design: Overlays are fully customizable with CSS and will adapt to any screen size and orientation. You can set a flexible minimum and maximum width and height to the overlay, as well as media queries.
  • Always visible: If the height of the overlay exceeds the visible area, vertical scrolling will be automatically enabled to prevent the off-screen content from being unreachable.
  • Accessible: Keyboard navigable using Tab key. WAI-ARIA roles are added automatically if missing. Text resizing or zooming will not break the layout, visibility, or position of the popup.
  • Device independent: Works well on desktops, tablets, most modern phones and other devices. Optimized and tested in all modern browsers including IE7+, and in new versions of popular screen readers including JAWS, NVDA, and VoiceOver.
  • Flexible and customizable: Supports multiple popup instances, custom CSS3 animations and transitions...

Usage

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Site Title</title>
</head>
<body>

  <!-- Add a page container (optional) -->
  <div class="my-page-container">
    {{ Page Content }}
    <!-- Add a button to open the popup (optional) -->
    <button class="my_popup_open">Open popup</button>
  </div>

  <!-- Add content to the popup -->
  <div id="my_popup">
    {{ Popup Content }}
    <!-- Add a button to close the popup (optional) -->
    <button class="my_popup_close">Close</button>
  </div>

  <!-- Include jQuery -->
  <script src="https://code.jquery.com/jquery-1.8.2.min.js"></script>

  <!-- Include jQuery Popup Overlay -->
  <script src="https://cdn.jsdelivr.net/gh/vast-engineering/jquery-popup-overlay@2/jquery.popupoverlay.min.js">
  </script>

  <script>
    $(document).ready(function() {

      // Initialize the plugin
      $('#my_popup').popup();

      // Set page container as a default option for all popups (optional, but highly recommended)
      $.fn.popup.defaults.pagecontainer = '#my-page-container'
    });
  </script>

</body>
</html>

It can also be used as a NPM package:

npm install jquery-popup-overlay

And included as a CommonJS module:

var popup = require("jquery-popup-overlay");

Options

Name Type Default Description
autoopen boolean false Shows the popup when initialized.
autozindex boolean false

Sets highest z-index of all elements of the page to the popup.

background boolean true Enables background cover.
Default is false for tooltips.
blur boolean true Closes the popup if a user clicks on a background content or cover, or anywhere outside the popup.
closeelement string (CSS selector) '.{popup_id}_close' Enables you to define custom element which will close the popup on click. By default, in our case it's set to .my_popup_close.
color string (CSS color) '#000' Sets background color.
detach boolean false

Removes popup element from the DOM after closing transition.

escape boolean true Closes the popup when Escape key is pressed.
focuselement string (CSS selector) '#{popup_id}' Enables you to specify the element which will be focused upon showing the popup. By default, the popup element #my_popup will recieve the initial focus.
horizontal 'center'
'left'
'right'
'leftedge'
'rightedge'
'center'

Sets horizontal position.

Options `leftedge` and `rightedge` can be used only for tooltips, and will align the tooltip to the left or right edge of the opening element (`openelement`).

keepfocus boolean true Lock keyboard focus inside of popup. Recommended to be enabled.
offsettop number 0

Sets top offset to tooltip.

offsetleft number 0

Sets left offset to tooltip.

opacity float 0.5 Sets background opacity.
outline boolean false

Shows a default browser outline on popup element when focused.

Setting to false is equivalent to #my_popup{outline: none;}.

openelement string (CSS selector) '.{popup_id}_open' Enables you to define custom element which will open the popup on click. By default, in our case it's set to .my_popup_open.
pagecontainer string (CSS selector) null

Sets a page container (to improve iOS and screen-reader experience). Page container should be a direct child of <body>, a top level element that surrounds all content of the page (e.g. #pagecontainer on this page).

It's highly recommended that you set the page container to help some screen readers read the modal dialog correctly. Doing so, when the popup is visible, aria-hidden="true" will be set to the page container and aria-hidden="false" to the popup, and vice-versa when the popup closes.

Setting `pagecontainer` will also enable blur option to work correctly on tooltips and popups without background. See Issue 90.

You can set `pagecontainer` once per website. For example:
$.fn.popup.defaults.pagecontainer = '#pagecontainer';

(We might also use this element in the future to lock the scrolling of background content in iOS. Issue 57.)

setzindex boolean true Sets default z-index to the popup (2001) and to the background (2000).
scrolllock boolean false Disables scrolling of background content while the popup is visible.
transition string (CSS transition) null

Sets CSS transition when showing and hiding a popup.

Use this if you don't need separate transition for background, or different transition for opening and closing the popup, or if you need to transition only selected properties – otherwise set custom transitions directly in CSS.

Simple fade effect $('#my_popup').popup({transition: 'all 0.3s'}) is equivalent to #my_popup, #my_popup_wrapper, #my_popup_background {transition: all 0.3s;}

Setting fade effect for all popups on the site: $.fn.popup.defaults.transition = 'all 0.3s'; is equivalent to .popup_content, .popup_wrapper, .popup_background {transition: all 0.3s;}

tooltipanchor object
JQuery or DOM object
null

Sets an element to be an anchor for tooltip position.

For example, for multiple opening links using the same tooltip on mouseover:

$('.my_popup_open').on({
  mouseenter: function(event) {
    $('#my_popup').popup({
      tooltipanchor: event.target,
      autoopen: true,
      type: 'tooltip'
    });
  },
  mouseleave: function() {
    $('#my_popup').popup('hide');
  }
});
type 'overlay'
'tooltip'
'overlay' Sets popup type to overlay or tooltip.
vertical 'center'
'top'
'bottom'
'topedge'
'bottomedge'
'center'

Sets vertical position.

Options `topedge` and `bottomedge` can be used only for tooltips, and will align the tooltip to the top or bottom edge of the opening element (`openelement`).

Example:

$('#my_popup').popup({
  opacity: 0.3,
  transition: 'all 0.3s'
});

Callback events

Name Type Description
beforeopen function Callback function which will execute before the popup is opened.
onopen function Callback function which will execute when the popup starts to open.
onclose function Callback function which will execute when the popup starts to close.
opentransitionend function Callback function which will execute after the opening CSS transition is over, only if transition actually occurs and if supported by the browser.
closetransitionend function Callback function which will execute after the closing CSS transition is over, only if transition actually occurs and if supported by the browser.

Example:

$('#my_popup').popup({
  onopen: function() {
    alert('Popup just opened!');
  }
});

Defaults

Default values for options and events can be modified.

Example:

$.fn.popup.defaults.transition = 'all 0.3s';
$.fn.popup.defaults.pagecontainer = '.container';

Methods

Name Description
.popup(options)

Activates your content as a popup. Accepts an optional options object.

$('#my_popup').popup({
  background: false
});
.popup('show')

Manually opens a popup.

$('#my_popup').popup('show');
.popup('hide')

Manually hides a popup.

$('#my_popup').popup('hide');
.popup('toggle')

Manually toggles a popup.

$('#my_popup').popup('toggle');
.popup('reposition')

Manually re-positions a popup.

$('#my_popup').popup('reposition');

This method is triggered automatically on every show, and on window.resize event for tooltips. Perhaps you might find some use of it.


Changelog

See the changelog on GitHub.



Basic

$('#basic').popup();

Try to change the width and height of browser window, or to rotate your device.

Also try to navigate with the Tab key

The dialog can be closed by pressing the Esc key, or by clicking on the background
outside the content area, or by clicking on the Close button.

Generated close button

closebutton: true option will append markup for the close button (at top right).

$('#closebutton').popup({
  closebutton: true
});

Additionally, custom markup can be provided via closebuttonmarkup option.

Fade

CSS transitions can be set via options:

$('#fade').popup({
  transition: 'all 0.3s'
});

Or you can set transitions directly in CSS:

$('#fade').popup();
#fade,
#fade_wrapper,
#fade_background {
  transition: all 0.3s;
}

Scrolllock

Scrolling can be locked with scrollock option.

$('#scrolllock').popup({
  scrolllock: true
});

Fade & Scale

$('#fadeandscale').popup({
  transition: 'all 0.3s'
});
#fadeandscale {
  transform: scale(0.8);
}
.popup_visible #fadeandscale {
  transform: scale(1);
}

Slide-in

If you are using slide-in or any animation that is getting the popup out of the viewport, use focusdelay that is longer than transition-duration, it will make animations more smooth in Chrome on Android which tries to get the focused element to the viewport and conflicts the animation.

outline controls the outline visibility on the popup. It is optional and added just for demonstration.

$('#slide').popup({
  vertical: 'top',
  outline: true,
  focusdelay: 400 // for smoother slide-in animations on Android
});

#slide_background {
  transition: all 0.3s 0.3s;
}
#slide,
#slide_wrapper {
  transition: all 0.3s ease-out;
}
#slide {
  transform: translateX(0) translateY(-40%);
}
.popup_visible #slide {
  transform: translateX(0) translateY(0);
}

Stand-alone

$('#standalone').popup({
  color: 'white',
  opacity: 1,
  transition: '0.3s',
  scrolllock: true
});

#standalone {
  transform: scale(0.8);
}
.popup_visible #standalone {
  transform: scale(1);
}

Active background

background: false will enable interaction with background content (hover, click, etc.), while the popup is visible, as the background div will not be added to DOM.

horizontal and horizontal will set the position.

$('#fade').popup({
  background: false,
  horizontal: 'right',
  vertical: 'bottom'
});

Active background absolute

Use absolute: true if you want to have absolute (not fixed) position of the popup.

blur:false will keep the popup visible, even after clicking on background content.

$('#fade').popup({
  background: false,
  blur: false,
  absolute: true
});

Inactive background

color: 'transparent' will print a transparent background and prevent (initial) interaction with background content, so it will require 2 clicks to interact with background content, in case blur:false is not set.

$('#fade').popup({
  color: 'transparent'
});

Tooltip example

By default, tooltip content will be positioned relative to the opening link, else it will fallback to {left: 0, top:0}.

tooltipanchor can be used to override the default.

$('#my_tooltip').popup({
  type: 'tooltip',
  vertical: 'top',
  horizontal: 'center',
  tooltipanchor: $('#my_tooltip_open')
});

Callback events

$('#fall').popup({
        beforeopen: function () {
            alert('beforeopen');
        },
        onopen: function () {
            alert('onopen');
        },
        onclose: function () {
            alert('onclose');
        },
        opentransitionend: function () {
            alert('opentransitionend');
        },
        closetransitionend: function () {
            alert('closetransitionend');
        }
    });

Other examples

See other examples on JSBin: