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
This is a completely basic popup, no options set.
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,
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
Here is a tiny popup being used like a tooltip. The text will wrap to multiple lines as needed.
Learn how to customize and extend popups by working with the API, custom scripts, and styles.Scaling images Map + video iframes Overlay panels
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();
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" )
Popups can be closed either by clicking outside the popup widget or by pressing the
Esc key. Popups can also be closed via the
$( "#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).
Popup with close button right Popup with close button left
<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>
I have a close button at the top right corner with simple HTML markup.
I have a close button at the top left corner with simple HTML markup.
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
This is a popup with the
ui-content class added to the popup container.
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.
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
It's also possible to specify any valid selector as the value of
position-to in addition to
window. For example, you adding
data-position-to="#myElement" will position the popup over the element with the id
<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
I am positioned to the window.
I am positioned over the origin.
I am positioned over the code sample via selector.
The popup's placement constraints, which may cause the popup not to appear centered as desired, are as follow:
max-widthto the width of the window minus a tolerance of 15px on either side.
See methods for information about setting the popup position programmatically, including the option to specify x and y coordinates.
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
I'm a simple popup.
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.
popup plugin provides two theme-related options:
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.
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>
data-theme="a" set on me
I have a
data-overlay-theme="a" set on me
data-overlay-theme="a" set on me
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