Popup Widget


Popup Widgetversion added: 1.2

Description: Opens content in a popup.

QuickNavExamples

Popups

To create a popup, add the data-role="popup" attribute to a div with the popup contents. Then create a link with the href set to the id of the popup div, and add the attribute data-rel="popup" to tell the framework to open the popup when the link is tapped. This is a similar markup pattern to the dialog widget. A popup div has to be nested inside the same page as the link.

Theming

The popup widget uses the jQuery Mobile CSS framework to style its look and feel. If popup specific styling is needed, the following CSS class names can be used for overrides or as keys for the classes option:

  • ui-popup-container: Outermost container for listview widget. Additionally, ui-popup-active class will be added when popup is active and ui-popup-hidden, ui-popup-truncate classes will be added when popup is inactive.
    • ui-popup: Main container of popup which withhelds all the content
      • ui-popup-arrow-guide: Guide of the arrow.
      • ui-popup-arrow-container: Container for the arrow of the popup. This will additionally have ui-popup-arrow-l, ui-popup-arrow-t, ui-popup-arrow-r, ui-popup-arrow-b classes accordingly if arrow is set to left, top, right or bottom respectively.
        • ui-popup-arrow: Main arrow element
1
2
3
4
5
<a href="#popupBasic" data-rel="popup">Open Popup</a>
<div data-role="popup" id="popupBasic">
<p>This is a completely basic popup, no options set.</p>
</div>

This will result in the following popup:

The popup consists of two elements: the screen, which is a transparent or translucent element that covers the entire document, and the container, which is the popup itself. If your original element had an id attribute, the screen and the container will each receive an id attribute based on it. The screen's id will be suffixed with "-screen", and the container's id will be suffixed with "-popup" (in the above example, id="popupBasic-screen" and id="popupBasic-popup", respectively).

The framework adds a small amount of margin to text elements, but it's really just a container with rounded corners and a shadow which serves as a blank slate for your designs (even these features can be disabled via options). Please note that if you want to add a header to the popup and also have a closing button, the markup for the header must come first.

This simple styling makes it easy to add in widgets to create a variety of different interactions. Here are a few real-world examples that combine the various settings and styles you can achieve out of the box with popups:

Scaling images: Lightbox examples

The framework CSS contains rules that make images that are immediate children of the popup scale to fit the screen. Because of the absolute positioning of the popup container and screen, the height is not adjusted to screen height on all browsers. You can prevent vertical scrolling with a simple script that sets the max-height of the image.

In the two examples below the divs with data-role="popup" have a class of photopopup.

The handler is bound to the popupbeforeposition event, which ensures the image is not only scaled before it is shown but also when the window is resized (e.g. orientation change). In this code example the height is reduced by 60 to take a top and bottom tolerance of 30 pixels into account.

1
2
3
4
5
6
7
8
$( document ).on( "pagecreate", function() {
$( ".photopopup" ).on({
popupbeforeposition: function() {
var maxHeight = $( window ).height() - 60 + "px";
$( ".photopopup img" ).css( "max-height", maxHeight );
}
});
});

Working with iframes in popups

You may need to embed an iframe into a popup to use a 3rd party widget. Here, we'll walk through a few real-world examples of working with iframes: videos and maps.

Video example

Here is an example of a 3rd party video player embedded in a popup:

The markup is an iframe inside a popup container. The popup will have a 15 pixels padding because of class ui-content and a one pixel border because the framework will add class ui-body-a to the popup.

1
2
3
4
5
<div data-role="popup" id="popupVideo" data-overlay-theme="b" data-theme="a" data-tolerance="15,15" class="ui-content">
<iframe src="http://player.vimeo.com/video/41135183" width="497" height="298" seamless></iframe>
</div>

When using an iframe inside a popup it is important to initially set the width and height attributes to 0. This prevents the page to breaking on platforms like Android 2.3. Note that you have to set the attributes, because setting the width and height with CSS is not sufficient. You can leave the actual width and height in the markup for browsers that have JavaScript disabled and use attr() to set the zero values upon the pageinit event.

Next, bind to the popupbeforeposition event to set the desired size of the iframe when the popup is shown or when the window is resized (e.g. orientation change). For the iframe examples on this page a custom function scale() is used to scale down the iframe to fit smaller screens. Expand the section below to view the code of this function.

scale()

The window width and height are decreased by 30 to take the tolerance of 15 pixels at each side into account.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
function scale( width, height, padding, border ) {
var scrWidth = $( window ).width() - 30,
scrHeight = $( window ).height() - 30,
ifrPadding = 2 * padding,
ifrBorder = 2 * border,
ifrWidth = width + ifrPadding + ifrBorder,
ifrHeight = height + ifrPadding + ifrBorder,
h, w;
if ( ifrWidth < scrWidth && ifrHeight < scrHeight ) {
w = ifrWidth;
h = ifrHeight;
} else if ( ( ifrWidth / scrWidth ) > ( ifrHeight / scrHeight ) ) {
w = scrWidth;
h = ( scrWidth / ifrWidth ) * ifrHeight;
} else {
h = scrHeight;
w = ( scrHeight / ifrHeight ) * ifrWidth;
}
return {
'width': w - ( ifrPadding + ifrBorder ),
'height': h - ( ifrPadding + ifrBorder )
};
};

Note: This function is not part of the framework. Copy the code into your script to use it.

When the popup is closed the width and height should be set back to 0. You can do this by binding to the popupafterclose event.

This is the complete script and the link to open the video popup:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$( document ).on( "pageinit", function() {
$( "#popupVideo iframe" )
.attr( "width", 0 )
.attr( "height", 0 );
$( "#popupVideo" ).on({
popupbeforeposition: function() {
var size = scale( 497, 298, 15, 1 ),
w = size.width,
h = size.height;
$( "#popupVideo iframe" )
.attr( "width", w )
.attr( "height", h );
},
popupafterclose: function() {
$( "#popupVideo iframe" )
.attr( "width", 0 )
.attr( "height", 0 );
}
});
});

Note that the video will still be playing in the iframe when the popup is closed. If available you can use the 3rd party API to stop the video on the popupafterclose event. Another way is to create the iframe when the popup is opened and destroy it when the popup is closed, but this would drop support for browsers that have JavaScript disabled.

Map example

In the second example, an iframe is used to display Google Maps API. Using an iframe prevents issues with the controls of the map.

This is the markup of the popup including a right close button:

1
2
3
4
5
6
7
<div data-role="popup" id="popupMap" data-overlay-theme="b" data-theme="b" data-corners="false" data-tolerance="15,15">
<a href="#" data-rel="back" data-role="button" data-theme="b" data-icon="delete" data-iconpos="notext" class="ui-btn-right">Close</a>
<iframe src="map.html" width="480" height="320" seamless></iframe>
</div>

Expand the section below to view the source of the iframe.

map.html

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Map</title>
<script>
function initialize() {
var myLatlng = new google.maps.LatLng( 51.520838, -0.140261 );
var myOptions = {
zoom: 15,
center: myLatlng,
mapTypeId: google.maps.MapTypeId.ROADMAP
}
var map = new google.maps.Map( document.getElementById( "map_canvas" ), myOptions );
}
</script>
<script src="http://maps.google.com/maps/api/js?sensor=false"></script>
<style>
html {
height: 100%;
overflow: hidden;
}
body {
margin: 0;
padding: 0;
height: 100%;
}
#map_canvas {
height: 100%;
}
</style>
</head>
<body onload="initialize()">
<div id="map_canvas"></div>
</body>
</html>

Setting the size of the iframe is done exactly the same as for the video example, with one exception. You should also set the width and height of the div that contains the map to prevent the page from breaking on platforms like Android 2.3. In this example the ID of this div is #map_canvas.

This is the complete script and the link to open the map popup:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
$( document ).on( "pageinit", function() {
$( "#popupMap iframe" )
.attr( "width", 0 )
.attr( "height", 0 );
$( "#popupMap iframe" ).contents().find( "#map_canvas" )
.css( { "width" : 0, "height" : 0 } );
$( "#popupMap" ).on({
popupbeforeposition: function() {
var size = scale( 480, 320, 0, 1 ),
w = size.width,
h = size.height;
$( "#popupMap iframe" )
.attr( "width", w )
.attr( "height", h );
$( "#popupMap iframe" ).contents().find( "#map_canvas" )
.css( { "width": w, "height" : h } );
},
popupafterclose: function() {
$( "#popupMap iframe" )
.attr( "width", 0 )
.attr( "height", 0 );
$( "#popupMap iframe" ).contents().find( "#map_canvas" )
.css( { "width": 0, "height" : 0 } );
}
});
});

Calling the popup plugin

This plugin will autoinitialize on any page that contains a div with the attribute data-role="popup". However, if needed you can directly call the popup plugin on any selector, just like any jQuery plugin and programmatically work with the popup options, methods, and events API:

1
$( "#myPopupDiv" ).popup();

Opening popups

Using the markup-based configuration, when a link with the data-rel="popup" is tapped, the corresponding popup container with the id referenced in the href of the link will be shown. To open a popup programmatically, call popup with the open method on the popup container:

1
$( "#myPopupDiv" ).popup( "open" )

Closing popups

By default popups can be closed either by clicking outside the popup widget or by pressing the Esc key. To prevent this, the data-dismissible="false" attribute can be added to the popup. Popups can also be closed via the close method:

1
$( "#myPopupDiv" ).popup( "close" )

To add an explicit close button to a popup, add a link with the role of button into the popup container with a data-rel="back" attribute which will close the popup when tapped. We have created helper classes to position buttons in the upper left (ui-btn-left) or upper right (ui-btn-right) of the popup but you may need to tweak these or add custom positioning styles depending on your design. We recommend adding standard content padding to the popup to make room for the buttons (see next section).

1
2
3
4
<div data-role="popup">
<a href="#" data-rel="back" data-role="button" data-theme="a" data-icon="delete" data-iconpos="notext" class="ui-btn-right">Close</a>
...popup contents go here...
</div>

Adding padding

For popups with formatted text, padding is needed. We recommend adding the ui-content class to the popup container which adds the standard 1em (16px) of padding, just like the page content container. Write your own styles to create a more customized design if needed.

1
2
3
4
5
<a href="#popupPadded" data-rel="popup" data-role="button">Popup with padding</a>
<div data-role="popup" id="popupPadded" class="ui-content">
<p>This is a popup with the <code>ui-content</code> class added to the popup container.</p>
</div>

This will result in the following popup with content padding:

When padding is added, we apply a few style rules to negate the top margin for the first heading or paragraph in the popup and do the same for the last element's bottom margin. This keep the popups from having too much vertical space when the content padding and element margins combine.

Positioning options

By default, popups open centered vertically and horizontally over the thing you clicked (the origin) which is good for popups used as tooltips or menus. The framework also applies some basic collision detection rules to ensure that the popup will appear on-screen so the ultimate position may not always be centered over the origin.

For situations like a dialog or lightbox where the popup should appear centered within the window instead of over the origin, add the data-position-to attribute to the link and specify a value of window.

It's also possible to specify any valid selector as the value of position-to in addition to origin and window. For example, if you add data-position-to="#myElement" the popup will be positioned over the element with the id myElement.

A few examples:

The popup's placement constraints, which may cause the popup not to appear centered as desired, are as follow:

  1. The width of the popup will be limited using CSS max-width to the width of the window minus a tolerance of 15px on either side.
  2. A tolerance from the edges of the window (15px from each of the sides and 30px from the top and the bottom) will be observed when the popup fits inside the window. Tall popups are allowed to overflow the top and bottom edges of the window. Those parts of the popup can be viewed by manually scrolling the document. This tolerance can be configured via the tolerance option.
  3. The top coordinate of the popup will never be negative. This ensures that the top of the popup will not be cut off.
  4. If centering the popup over an element would cause the overall height of the document to increase, the popup is shifted upwards at most until its top coordinate becomes 0.

Also note that a popup is currently always placed at the center of the window after an orientation change or window resize event.

See methods for information about setting the popup position programmatically, including the option to specify x and y coordinates.

Setting transitions

By default, popups have no transition to make them open as quickly as possible. To set the transition used for a popup, add the data-transition attribute to the link that references the popup. The reverse version of the transition will be used when closing the popup.

1
2
3
<a href="#transitionExample" data-transition="flip" data-rel="popup">
Flip transition
</a>

For performance reasons on mobile devices, we recommend using simpler transitions like pop, fade or none for smooth and fast popup animations, especially with larger or complex widgets within a popup. To view all transition types, you must be on a browser that supports 3D transforms. By default, devices that lack 3D support (such as Android 2.x) will fallback to "fade" for all transition types. See the transitions page for detailed information on the transition system.

When you launch the popup from any of the buttons, the data-transition set on the button will be used. However, if you launch the popup programmatically, such as via $( "#transitionExample" ).popup( "open" ), the data-transition attribute specified in the definition of the popup will be used if present.

Theming the popup and overlay

The popup plugin provides two theme-related options: data-theme and data-overlay-theme. The data-theme option refers to the theme of the popup itself, whereas data-overlay-theme refers to the theme of the popup's background, which covers the entire window behind the popup.

data-theme will be inherited from the page, and will always have a valid value when the popup opens, unless you explicitly specify data-theme="none", in which case the popup will have a transparent background.

The data-overlay-theme will never be set, and the popup's background, although always present when the popup is shown, will be completely transparent, unless explicitly set using for example data-overlay-theme="b". In this case, the background will fade in, partially obscuring the rest of the window, to further direct attention to the popup. Here is an example of an explicitly themed popup:

1
2
3
<div id="both" data-role="popup" data-theme="b" data-overlay-theme="a" class="ui-content">
...Popup contents...
</div>

Arrows

The extension widgets/popup.arrow provides the arrow option, which is also exposed as a data attribute. For example, data-arrow="t,b" will result in the popup being displayed with a top or a bottom arrow.

When an arrow is requested using the arrow option, the popup is positioned along one of the edges of the popup such that the arrow points at the center of the origin. The value of the arrow option is a comma-separated list of letters referring to the edges of the popup along which the framework should attempt to place the arrow:

t The framework should attempt to place the popup such that the arrow somewhere along the top edge of the popup points at the center of the origin.
r The framework should attempt to place the popup such that the arrow somewhere along the right edge of the popup points at the center of the origin.
b The framework should attempt to place the popup such that the arrow somewhere along the bottom edge of the popup points at the center of the origin.
l The framework should attempt to place the popup such that the arrow somewhere along the left edge of the popup points at the center of the origin.

For each edge given in the list, the framework calculates

  1. the distance between the tip of the arrow and the center of the origin, and
  2. whether minimizing the above distance would cause the arrow to appear too close to one of the corners of the popup along the given edge.
If the second condition applies, the edge is discarded as a possible solution for placing the arrow. Otherwise, the calculated distance is examined. If it is 0, meaning that the popup can be placed exactly such that the tip of the arrow points at the center of the origin, no further edges are examined, and the popup is positioned along the last examined edge. Thus, the order in which the edges are given matters.

The example below shows a popup with an arrow either along its left edge or along its top edge.

1
2
3
4
<div data-role="popup" data-arrow="l,t" class="ui-content">
<h2>Popup with an arrow</h2>
<p>A second paragraph.</p>
</div>

Note: Chaining of popups not allowed

The framework does not currently support chaining of popups so it's not possible to embed a link from one popup to another popup. All links with a data-rel="popup" inside a popup will not do anything at all.

This also means that custom select menus will not work inside popups, because they are themselves implemented using popups. If you place a select menu inside a popup, it will be rendered as a native select menu, even if you specify data-native-menu="false".

A workaround to get chained popups working is the use of a timeout for example in the popupafterclose event bound to the invoking popup. In the following example, when the first popup is closed, the second will be opened by a delayed call to the open method:

1
2
3
4
5
6
7
$( document ).on( "pageinit", function() {
$( ".popupParent" ).on({
popupafterclose: function() {
setTimeout(function() { $( ".popupChild" ).popup( "open" ) }, 100 );
}
});
});

Providing pre-rendered markup

You can improve the load time of your page by providing the markup that the popup widget would normally create during its initialization.

By providing this markup yourself, and by indicating that you have done so by setting the attribute data-enhanced="true", you instruct the popup widget to skip these DOM manipulations during instantiation and to assume that the required DOM structure is already present.

When you provide such pre-rendered markup you must also set all the classes that the framework would normally set, and you must also set all data attributes whose values differ from the default to indicate that the pre-rendered markup reflects the non-default value of the corresponding widget option.

The popup widget moves the element on which it is instantiated such that it becomes the last child element of a page div or, if the element is not inside a page, it will become the last child element of the body. It then wraps the element in a container div, and prepends a newly created element that serves as the modal overlay screen to the parent of the container.

The example below includes an entire jQuery Mobile page rather than just the popup. This helps illustrate where you must place the markup for the pre-rendered popup widget in relation to the jQuery Mobile page on which it is to appears. In the example, the popup has the attribute data-overlay-theme="b" to reflect the fact that the modal overlay screen has an associated theme.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<div data-role="page">
<div data-role="header">
<h1>Example Page</h1>
</div>
<div role="main" class="ui-content">
<a href="#pre-rendered" data-rel="popup" class="ui-btn ui-corner-all ui-shadow ui-btn-inline">Open pre-rendered popup</a>
</div>
<!-- the following two divs represent the pre-rendered popup widget -->
<div class="ui-popup-screen ui-overlay-b ui-screen-hidden"></div>
<div class="ui-popup-container ui-popup-hidden ui-popup-truncate" id="pre-rendered-popup">
<div class="ui-popup ui-body-inherit ui-overlay-shadow ui-corner-all" id="pre-rendered" data-role="popup" data-enhanced="true" data-overlay-theme="b">
<p>Pre-rendered popup</p>
</div>
</div>
</div>

ID generation

The popup widget adds an ID to the elements it generates. The ID for any given generated element is constructed by suffixing the popup's own ID:

Placeholder
<popup-id>-placeholder
Screen
<popup-id>-screen
Container
<popup-id>-popup

For example, creating a popup with

1
2
3
<div id="extra-info" data-role="popup">
<p>To use this feature, enable it from Settings.</p>
</div>

will result in the following markup:

1
2
3
4
5
6
7
8
9
<div id="extra-info-placeholder" style="display: none;">
<!-- placeholder for extra-info -->
</div>
<div id="extra-info-screen" class="ui-screen-hidden ui-popup-screen ui-overlay-inherit"></div>
<div id="extra-info-popup" class="ui-popup-container ui-popup-hidden ui-popup-truncate">
<div id="extra-info" data-role="popup" class="ui-popup ui-body-inherit ui-overlay-shadow ui-corner-all">
<p>To use this feature, enable it from Settings.</p>
</div>
</div>

Options

arrow 

Type: String or Boolean
Default: ""
Sets whether to draw the popup with an arrow.

This option is provided by the widgets/popup.arrow extension.

This option is also exposed as a data attribute: data-arrow="t,b".

The following values are valid: true, false, or a string containing a comma-separated list of the letters "l", "t", "r", and "b". The list may be empty, in which case it corresponds to a value of false. The value true corresponds to the list "l,t,r,b". This list indicates along which edges the code should attempt to place the arrow. The code tries to place the arrow along each edge given in the list in the left-to-right order given in the list until one such placement would result in the arrow pointing exactly at the desired coordinates. If no arrows can be displayed the popup is positioned as though the value of this option were false.

Multiple types supported:
  • String: A comma-separated list of the letters "l", "t", "r", and "b".
  • Boolean: A value of true is equivalent to a value of "t,r,b,l", whereas false indicates that no arrow is to be shown.
Code examples:

Initialize the popup with the arrow option specified:

1
2
3
$( ".selector" ).popup({
arrow: "l,t,r,b"
});

Get or set the arrow option, after initialization:

1
2
3
4
5
// Getter
var arrow = $( ".selector" ).popup( "option", "arrow" );
// Setter
$( ".selector" ).popup( "option", "arrow", "l,t,r,b" );

classes 

Type: Object
Default:
{
"ui-popup": "ui-corner-all ui-overlay-shadow",
"ui-popup-arrow": "ui-overlay-shadow"
}

Specify additional classes to add to the widget's elements. Any of classes specified in the Theming section can be used as keys to override their value. To learn more about this option, check out the learn article about the classes option.

Code examples:

Initialize the popup with the classes option specified, changing the theming for the ui-popup class:

1
2
3
4
5
$( ".selector" ).popup({
classes: {
"ui-popup": "highlight"
}
});

Get or set a property of the classes option, after initialization, here reading and changing the theming for the ui-popup class:

1
2
3
4
5
// Getter
var themeClass = $( ".selector" ).popup( "option", "classes.ui-popup" );
// Setter
$( ".selector" ).popup( "option", "classes.ui-popup", "highlight" );

corners 

Type: Boolean
Default: true

Sets whether to draw the popup with rounded corners.

This option is also exposed as a data attribute: data-corners="false".

Code examples:

Initialize the popup with the corners option specified:

1
2
3
$( ".selector" ).popup({
corners: false
});

Get or set the corners option, after initialization:

1
2
3
4
5
// Getter
var corners = $( ".selector" ).popup( "option", "corners" );
// Setter
$( ".selector" ).popup( "option", "corners", false );

defaults 

Type: Boolean
Default: false
Seting this option to true indicates that other widgets options have default values and causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves option values from data attributes. This can improve startup time.

This option is also exposed as a data attribute: data-defaults="true".

Code examples:

Initialize the popup with the defaults option specified:

1
2
3
$( ".selector" ).popup({
defaults: true
});

Get or set the defaults option, after initialization:

1
2
3
4
5
// Getter
var defaults = $( ".selector" ).popup( "option", "defaults" );
// Setter
$( ".selector" ).popup( "option", "defaults", true );

disabled 

Type: Boolean
Default: false
Disables the popup if set to true.

This option is also exposed as a data attribute: data-disabled="true".

Code examples:

Initialize the popup with the disabled option specified:

1
2
3
$( ".selector" ).popup({
disabled: true
});

Get or set the disabled option, after initialization:

1
2
3
4
5
// Getter
var disabled = $( ".selector" ).popup( "option", "disabled" );
// Setter
$( ".selector" ).popup( "option", "disabled", true );

dismissible 

Type: Boolean
Default: true

Sets whether clicking outside the popup or pressing Escape while the popup is open will close the popup.

Note: When history support is turned on, pressing the browser's "Back" button will dismiss the popup even if this option is set to false.

This option is also exposed as a data attribute: data-dismissible="false".

Code examples:

Initialize the popup with the dismissible option specified:

1
2
3
$( ".selector" ).popup({
dismissible: false
});

Get or set the dismissible option, after initialization:

1
2
3
4
5
// Getter
var dismissible = $( ".selector" ).popup( "option", "dismissible" );
// Setter
$( ".selector" ).popup( "option", "dismissible", false );

history 

Type: Boolean
Default: true

Sets whether to alter the url when a popup is open to support the back button.

This option is also exposed as a data attribute: data-history="false".

Code examples:

Initialize the popup with the history option specified:

1
2
3
$( ".selector" ).popup({
history: false
});

Get or set the history option, after initialization:

1
2
3
4
5
// Getter
var history = $( ".selector" ).popup( "option", "history" );
// Setter
$( ".selector" ).popup( "option", "history", false );

initSelector 

Type: Selector
Default: See below

The default initSelector for the popup widget is:

1
":jqmData(role='popup')"

Note: This option is deprecated in 1.4.0 and will be removed in 1.5.0.
As of jQuery Mobile 1.4.0, the initSelector is no longer a widget option. Instead, it is declared directly on the widget prototype. Thus, you may specify a custom value by handling the mobileinit event and overwriting the initSelector on the prototype:

1
2
3
$( document ).on( "mobileinit", function() {
$.mobile.popup.prototype.initSelector = "div.custom";
});

Note: Remember to attach the mobileinit handler after you have loaded jQuery, but before you load jQuery Mobile, because the event is triggered as part of jQuery Mobile's loading process.

The value of this option is a jQuery selector string. The framework selects elements based on the value of this option and instantiates popup widgets on each of the resulting list of elements.

(version deprecated: 1.4.0)

overlayTheme 

Type: String
Default: null

Sets the color scheme (swatch) for the popup background, which covers the entire window. If not explicitly set, the background will be transparent.

This option is also exposed as a data attribute: data-overlay-theme="b".

Code examples:

Initialize the popup with the overlayTheme option specified:

1
2
3
$( ".selector" ).popup({
overlayTheme: "b"
});

Get or set the overlayTheme option, after initialization:

1
2
3
4
5
// Getter
var overlayTheme = $( ".selector" ).popup( "option", "overlayTheme" );
// Setter
$( ".selector" ).popup( "option", "overlayTheme", "b" );

positionTo 

Type: String
Default: "origin"

Sets the element relative to which the popup will be centered. It has the following values:

"origin" When the popup opens, center over the coordinates passed to the open() call (see details on this method).
"window" When the popup opens, center in the window.
jQuery selector When the popup opens, create a jQuery object based on the selector, and center over it. The selector is filtered for elements that are visible with ":visible". If the result is empty, the popup will be centered in the window.

This option is also exposed as a data attribute: data-position-to="window".

Code examples:

Initialize the popup with the positionTo option specified:

1
2
3
$( ".selector" ).popup({
positionTo: "window"
});

Get or set the positionTo option, after initialization:

1
2
3
4
5
// Getter
var positionTo = $( ".selector" ).popup( "option", "positionTo" );
// Setter
$( ".selector" ).popup( "option", "positionTo", "window" );

shadow 

Type: Boolean
Default: true

Sets whether to draw a shadow around the popup.

This option is also exposed as a data attribute: data-shadow="false".

Code examples:

Initialize the popup with the shadow option specified:

1
2
3
$( ".selector" ).popup({
shadow: false
});

Get or set the shadow option, after initialization:

1
2
3
4
5
// Getter
var shadow = $( ".selector" ).popup( "option", "shadow" );
// Setter
$( ".selector" ).popup( "option", "shadow", false );

theme 

Type: String
Default: null, inherited from parent
Sets the color scheme (swatch) for the popup contents. Unless explicitly set to 'none', the theme for the popup will be assigned the first time the popup is shown by inheriting the page theme or, failing that, by the hard-coded value 'a'. If you set it to 'none', the popup will not have any theme at all, and will be transparent.

Possible values: swatch letter (a-z), or "none".

This option is also exposed as a data attribute: data-theme="b".

Code examples:

Initialize the popup with the theme option specified:

1
2
3
$( ".selector" ).popup({
theme: "b"
});

Get or set the theme option, after initialization:

1
2
3
4
5
// Getter
var theme = $( ".selector" ).popup( "option", "theme" );
// Setter
$( ".selector" ).popup( "option", "theme", "b" );

tolerance 

Type: String
Default: "30,15,30,15"

Sets the minimum distance from the edge of the window for the corresponding edge of the popup. By default, the values above will be used for the distance from the top, right, bottom, and left edge of the window, respectively.

You can specify a value for this option in one of four ways:

  1. Empty string, null, or some other falsy value. This will cause the popup to revert to the above default values.
  2. A single number. This number will be used for all four edge tolerances.
  3. Two numbers separated by a comma. The first number will be used for tolerances from the top and bottom edge of the window, and the second number will be used for tolerances from the left and right edge of the window.
  4. Four comma-separated numbers. The first will be used for tolerance from the top edge, the second for tolerance from the right edge, the third for tolerance from the bottom edge, and the fourth for tolerance from the left edge.

Code examples:

Initialize the popup with the tolerance option specified:

1
2
3
$( ".selector" ).popup({
tolerance: "0,0"
});

Get or set the tolerance option, after initialization:

1
2
3
4
5
// Getter
var tolerance = $( ".selector" ).popup( "option", "tolerance" );
// Setter
$( ".selector" ).popup( "option", "tolerance", "0,0" );

transition 

Type: String
Default: none

Sets the default transition for the popup. The default value will result in no transition.

If the popup is opened from a link, and the link has the data-transition attribute set, the value specified therein will override the value of this option at the time the popup is opened from the link.

Code examples:

Initialize the popup with the transition option specified:

1
2
3
$( ".selector" ).popup({
transition: "pop"
});

Get or set the transition option, after initialization:

1
2
3
4
5
// Getter
var transition = $( ".selector" ).popup( "option", "transition" );
// Setter
$( ".selector" ).popup( "option", "transition", "pop" );

Methods

close()Returns: jQuery (plugin only)

Closes the popup.
  • This method does not accept any arguments.
Code examples:

Invoke the close method:

1
$( ".selector" ).popup( "close" );

destroy()Returns: jQuery (plugin only)

Removes the popup functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
$( ".selector" ).popup( "destroy" );

disable()Returns: jQuery (plugin only)

Disables the popup.
  • This method does not accept any arguments.
Code examples:

Invoke the disable method:

1
$( ".selector" ).popup( "disable" );

enable()Returns: jQuery (plugin only)

Enables the popup.
  • This method does not accept any arguments.
Code examples:

Invoke the enable method:

1
$( ".selector" ).popup( "enable" );

open( options )Returns: jQuery (plugin only)

display the popup using the specified options.

If the x or y option is missing, and no jQuery selector is given as the value of the positionTo option, the middle of the window will be used.

The transition option can be used to override the popup's own transition option. This will result in the popup opening via the transition specified in the call, but the popup's transition option will not be updated.

Similarly, the positionTo option can be used to override the popup's default positioning without modifying the value of the popup's positionTo option. The values available for positionTo are the same as those for the popup's positionTo option.

  • options
    Type: Object
    • x (default: )
      Type: String
      The x-coordinate where the popup is to be displayed.
    • y (default: )
      Type: String
      The y-coordinate where the popup is to be displayed.
    • transition (default: )
      Type: String
      The transition to use during the opening sequence.
    • positionTo (default: )
      Type: String
      The positioning to use.
Code examples:

Invoke the open method:

1
$( ".selector" ).popup( "open", options );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
var isDisabled = $( ".selector" ).popup( "option", "disabled" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current popup options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
var options = $( ".selector" ).popup( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the popup option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
$( ".selector" ).popup( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the popup.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

1
$( ".selector" ).popup( "option", { disabled: true } );

reposition( options )Returns: jQuery (plugin only)

Change the on-screen position of the popup. See the open() method for a description of the keys recognized from the options object.
  • options
    Type: Object
    • x (default: )
      Type: Integer
      The x-coordinate where the popup is to be displayed.
    • y (default: )
      Type: Integer
      The y-coordinate where the popup is to be displayed.
    • positionTo (default: "origin")
      Type: String
      The positioning to use.
Code examples:

Invoke the reposition method:

1
$( ".selector" ).popup( "reposition", options );

Events

afterclose( event )Type: popupafterclose

Triggered when a popup has completely closed

This event is triggered when the popup has completely disappeared from the screen, meaning that all associated animations have completed.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the popup with the afterclose callback specified:

1
2
3
$( ".selector" ).popup({
afterclose: function( event, ui ) {}
});

Bind an event listener to the popupafterclose event:

1
$( ".selector" ).on( "popupafterclose", function( event, ui ) {} );

afteropen( event )Type: popupafteropen

Triggered after a popup has completely opened

This event is triggered when the popup has completely appeared on the screen, meaning that all associated animations have completed.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the popup with the afteropen callback specified:

1
2
3
$( ".selector" ).popup({
afteropen: function( event, ui ) {}
});

Bind an event listener to the popupafteropen event:

1
$( ".selector" ).on( "popupafteropen", function( event, ui ) {} );

beforeposition( event, ui )Type: popupbeforeposition

Triggered before a popup computes the coordinates where it will appear

This event is triggered when the popup has completed preparations for appearing on the screen, when the document is resized and the popup needs to move to another location, or when the reposition() method is called. At this point the popup has not yet started the opening animations and it has not yet calculated the coordinates where it will appear on the screen. Handling this event gives an opportunity to modify the content of the popup before it appears on the screen. For example, the content can be scaled or parts of it can be hidden or removed if it is too wide or too tall. You can also modify the options parameter to affect the popup's placement. The properties inside the options object available for modification are the same as those used by the reposition method.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the popup with the beforeposition callback specified:

1
2
3
$( ".selector" ).popup({
beforeposition: function( event, ui ) {}
});

Bind an event listener to the popupbeforeposition event:

1
$( ".selector" ).on( "popupbeforeposition", function( event, ui ) {} );

create( event, ui )Type: popupcreate

Triggered when the popup is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the popup with the create callback specified:

1
2
3
$( ".selector" ).popup({
create: function( event, ui ) {}
});

Bind an event listener to the popupcreate event:

1
$( ".selector" ).on( "popupcreate", function( event, ui ) {} );

Example:

A basic example of a Popup.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>popup demo</title>
<link rel="stylesheet" href="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.css">
<script src="//code.jquery.com/jquery-3.2.1.min.js"></script>
<script src="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.js"></script>
</head>
<body>
<div data-role="page" id="page1">
<div data-role="header">
<h1>jQuery Mobile Example</h1>
</div>
<div role="main" class="ui-content">
<a href="#popupBasic" data-rel="popup">Open Popup</a>
<div data-role="popup" id="popupBasic">
<p>This is a completely basic popup, no options set.</p>
</div>
</div>
</div>
</body>
</html>

Demo: