jQuery Mobile

Navigation Home

Popup API

The popup widget can be used for various types of popups. From a small tooltip popup to a large photo lightbox. Jump to section  

Popup basics

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. A popup div has to be nested inside the same page as the link.

Basic Popup

This is a completely basic popup, no options set.


A tooltip can be created by adding a theme swatch and padding via the ui-content class a basic popup.

A paragraph with a tooltip. Learn more

Here is a tiny popup being used like a tooltip. The text will wrap to multiple lines as needed.

Photo lightbox

A lightbox for displaying images can be created easily by placing an image in a popup. In this example, a close button is added to the markup by adding a link. The data-overlay-theme="a" attribute adds a dark backdrop behind the photos. For advanced photo techniques, see scaling images in popups.

Paris, France Sydney, Australia New York, USA


A menu can be created by adding a listview inside a popup.


Nested menu

A menu can be created by placing listviews into an accordion inside a popup.

Choose a creature...

Farm animals

Ocean Creatures

Wild Animals


A menu can be created by adding a listview inside a popup.

Sign in

Please sign in


Standard dialog markup can be placed into a popup. To create a modal style dialog, add the data-dismissible="false" attribute to the popup to prevent the click out to close behavior so people need to interact with popup buttons to close it.

Delete page...

Delete Page?

Are you sure you want to delete this page?

This action cannot be undone.

Cancel Delete

Adding padding

For popups with formatted text, padding is needed. The ui-content class to the popup container to adds the standard 15px of 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.

Popup with padding

This is a popup with the ui-content class added to the popup container.

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. 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 and position via a class

Right close button Left close button Undismissible Popup

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.


I have the data-dismissible attribute set to false. I'm not closeable by clicking outside of me.


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

Position to window Position to origin Position to #position-header

I am positioned to the window.

I am positioned over the origin.

I am positioned over the header for this section via selector. If the header isn't scrolled into view, collision detection will place the popup so it's in view.


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 transition will be used when closing the popup. For performance reasons on mobile devices, we recommend using simpler transitions like pop, fade or none for smooth and fast popup animations.

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

I'm a simple popup.


The popup has 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 controls the semi-opaque layer behind the popup. The theme is inherited from the page; specify data-theme="none" for a popup with a transparent background.

Theme A

I have data-theme="a" set on me

Theme "none", no shadow Overlay theme A

I have a data-overlay-theme="a" set on me

Theme E + overlay A

I have data-theme="e" and data-overlay-theme="a" set on me

Advanced techniques

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

Scaling images Map + video iframes