jQuery plugin for responsive and accessible modal windows and tooltips
Note: If you were using RawGit to get the script:
<script src="https://cdn.rawgit.com/vast-engineering/jquery-popup-overlay/gh-pages/jquery.popupoverlay.js"></script>
...and things started to break, change the src
to get the older version v1.7.13:
<script src="https://cdn.jsdelivr.net/gh/vast-engineering/jquery-popup-overlay@1.7.13/jquery.popupoverlay.min.js"></script>
RawGit is shutting down soon (jsDelivr seems like a good alternative, providing features like code minification and version locking), and our example code in the Usage section on this page used to point to the latest version of the script which might contain breaking changes.
If you want to upgrade from 1.x.x to 2.x.x version, the only breaking change in this release is that backgroundactive
option is removed. See all changes in the changelog on GitHub.
Basic Generated Close Button Fade Scroll-lock Fade & scale Active Bg Absolute Tooltip
<!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*) -->
<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-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
$('#JPO').popup();
// *Set default `pagecontainer` for all popups (optional, but recommended)
$.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");
See the Pen jquery-popup-overlay example by Vladimirs (@vladimirs) on CodePen.
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 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 .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 keyword 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 #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 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 |
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 .JPO_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. It's highly recommended that you set the page container for better iOS and screen-reader experience. Doing so, when the popup is visible, Setting `pagecontainer` will also enable You can set `pagecontainer` once per website. For example: We might also use this element 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 Setting fade effect for all popups on the site: |
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:
|
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:
|
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:
|
Default values for options and events can be modified. |
Example:
|
Name | Description |
---|---|
.popup(options) | Activates your content as a popup. Accepts an optional options
|
.popup('show') |
Manually opens a popup.
|
.popup('hide') |
Manually hides a popup.
|
.popup('toggle') |
Manually toggles a popup.
|
.popup('addclosebutton') |
Manually creates a Close button.
This method is triggered automatically on popup initialization if |
.popup('reposition') |
Manually re-positions a popup.
This method is triggered automatically every time a tooltip or a popup is opened, and on |
See the changelog on GitHub.
$('#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.
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;
}
Scrolling can be locked with scrollock
option.
$('#scrolllock').popup({
scrolllock: true
});
escape:false
disables hiding on Esc key.
blur:false
disables hiding on outer click.
$('#fadeandscale').popup({
escape: false,
blur: false,
transition: 'all 0.3s'
});
#fadeandscale {
transform: scale(0.8);
}
.popup_visible #fadeandscale {
transform: scale(1);
}
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);
}
$('#standalone').popup({
color: 'white',
opacity: 1,
transition: '0.3s',
scrolllock: true
});
#standalone {
transform: scale(0.8);
}
.popup_visible #standalone {
transform: scale(1);
}
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
});
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',
autozindex: true
});
type:'tooltip'
will use the opening link as an anchor for positioning. If it doesn't exist, it will fallback to top-left edge of the window.
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'
});
$('#fall').popup({
beforeopen: function () {
alert('beforeopen');
},
onopen: function () {
alert('onopen');
},
onclose: function () {
alert('onclose');
},
opentransitionend: function () {
alert('opentransitionend');
},
closetransitionend: function () {
alert('closetransitionend');
}
});