jQuery Popup Overlay

jQuery plugin for responsive and accessible modal windows and tooltips

Download View project on GitHub

NPM version

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>

  <!-- Wrap all page content in a page container (optional, but recommended for screen readers and iOS*) -->
  <div id="page">
    <header></header>
    <main>
      {{ Page Content }}
      <!-- Add a button to open the popup (optional) -->
      <button class="JPO_open">Open popup</button>
    </main>
    <footer></footer>
  </div>

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

  <!-- Include jQuery -->
  <script src="https://code.jquery.com/jquery-3.3.1.slim.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
      $('#JPO').popup();

      // Set default `pagecontainer` for all popups (optional, but recommended for screen readers and iOS*)
      $.fn.popup.defaults.pagecontainer = '#page'
    });
  </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");

Example on CodePen

See the Pen jquery-popup-overlay example by Vladimirs (@vladimirs) on CodePen.

Options

Name Type Default Description
absolute boolean false Sets absolute instead of fixed position to the popup. It will scroll with the rest of the content.
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 anywhere outside the popup.
blurignore string (CSS selector) true Sets elements which will be ignored in blur option, even if they are outside.
closeelement string (CSS selector) '.{popup_id}_close' Enables you to define custom element which will close the popup on click. In our case it's set to .JPO_close.
closebutton boolean null Dynamically creates a Close button during popup initialization by calling popup('addclosebutton') method. Use this if you don't want to hard-code Close elements in HTML template.
closebuttonmarkup object
jQuery or DOM object		 null Enables you to define custom markup which will be used for a dynamically created button. Use with closebutton option.
color string (CSS color) '#000' Sets background color.
detach boolean false

Removes popup element from the DOM. It will be appended to <body> when opened, and removed again when closed.
escape boolean true Closes the popup when Escape key is pressed.
focuselement boolean or 'closeelement' or string (CSS selector) '#{popup_id}' Enables you to specify the element which will be focused upon showing the popup. By default, the popup element (in our case #JPO) will recieve the initial focus. Setting to true will focus the popup even if keepfocus is false. A keyword 'closebutton' can be used to target a Close element.
focusdelay number (milliseconds) 50

Delays the focusing of the focuselement.

Use this if you have slide-in animations for the popup, to make them run smoothly in Chrome on Android, as it tries to get the focused element in the viewport so it conflicts with the animation. The delay should be longer than transition-duration.
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 .popup_content {outline:none;}.
openelement string (CSS selector) '.{popup_id}_open' Enables you to define custom element which will open the popup on click. In our case it's set to .JPO_open.
pagecontainer string (CSS selector) null

Sets a page container to help the plugin do its work. Page container should be a direct child of <body>, a top level element that surrounds all content of the page (e.g. #page on this page).

It's recommended that you set the page container for better screen-reader experience.

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. Some screen readers requires this in order to read the modal content properly.

iOS*: Setting `pagecontainer` will also enable blur:true option to work correctly on iOS if background:false option is set (tooltips have background:false by default). See Issue 90.

You can set `pagecontainer` once per website. For example:
$.fn.popup.defaults.pagecontainer = '#page';
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 $('#JPO').popup({transition: 'all 0.3s'}) is equivalent to #JPO, #JPO_wrapper, #JPO_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:

$('.JPO_open').on({
  mouseenter: function(event) {
    $('#JPO').popup({
      tooltipanchor: event.target,
      autoopen: true,
      type: 'tooltip'
    });
  },
  mouseleave: function() {
    $('#JPO').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:

$('#JPO').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:

$('#JPO').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 = '#page';

Methods

Name Description
.popup(options)

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

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

Manually opens a popup.

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

Manually hides a popup.

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

Manually toggles a popup.

$('#JPO').popup('toggle');
.popup('addclosebutton')

Manually creates a Close button.

$('#JPO').popup('addclosebutton');

This method is triggered automatically on popup initialization if closebutton option is set to true.
.popup('reposition')

Manually re-positions a popup.

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

This method is triggered automatically every time a tooltip or overlay is opened, and on window.resize event for tooltips.

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 them directly in CSS:

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

Scrolllock

Background scrolling can be locked with scrollock option.*

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

Fade & Scale Arrest

escape:false prevents closing on Esc key.

blur:false prevents closing on click outside the popup.

$('#fadeandscale').popup({
  escape: false,
  blur: false,
  scrolllock: true,
  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({
  focusdelay: 400, // for smoother slide-in animations on Android
  outline: true,
  vertical: 'top'
});


#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 vertical will set the position.

keepfocus:false will prevent locking tabbing inside of popup, and leave a focus on the opening element.

autozindex will keep the popup on top of all other elements on the page.

$('#active_background_fixed').popup({
  background: false,
  horizontal: 'right',
  vertical: 'bottom',
  keepfocus: false,
  autozindex: true,
  blur: false
});

Active background absolute

absolute:true keeps the popup in place when scrolling.

focuselement:'closebutton' will focus the Close element even if keepfocus is false.

$('#active_background_absolute').popup({
  absolute: true,
  background: false,
  keepfocus: false,
  focuselement: 'closebutton'
});

Tooltip

type:'tooltip' will use the opening link as an anchor for positioning. An anchor can be explicitly set with tooltipanchor option.

offsetleft and offsetleft will set the offset.

$('#tooltip').popup({
  type: 'tooltip',
  tooltipanchor: $('#tooltip_open'),
  offsetleft: 0,
  offsettop: '-15',
  vertical: 'top',
  horizontal: 'center'
});

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: