Popup

• Basics
• Options
• Methods
• Events

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.

<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:

Open 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).

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:

Tooltip Menu Nested menu Form Dialog Photo

Advanced popup techniques

Learn how to customize and extend popups by working with the API, custom scripts, and styles.

Scaling images Map + video iframes Overlay panels

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:

$( "#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:

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

Closing popups

Popups can be closed either by clicking outside the popup widget or by pressing the Esc key. Popups can also be closed via the close method:

$( "#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).

<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>
		

Popup with close button right Popup with close button left

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 15px of padding, just like the page content container. Write your own styles to create a more customized design if needed.

<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:

Popup with 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 href="#positionWindow" data-rel="popup" data-position-to="window">

<div data-role="popup" id="positionWindow">
	<p>I am positioned to the window.</p>
</div>

A few examples:

Position to window Position to origin Position to #codeSample

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 is a configurable 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.

<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.

No transition Pop Fade Flip Turn Flow Slide Slidefade Slide up Slide down

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="a". 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:

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

Theme A Theme "none", no shadow Overlay theme A Theme E + overlay A

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:

$( document ).on( "pageinit", function() {
    $( '.popupParent' ).on({
        popupafterclose: function() {
            setTimeout( function(){ $( '.popupChild' ).popup( 'open' ) }, 100 );
        }
    });
});