Dialog Widget


Dialog Widgetversion added: 1.0, deprecated: 1.4.0

Description: Opens content in an interactive overlay.

QuickNavExamples

Methods

Events

Note: Dialogs are deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. The dialog option provided by the page.dialog extension of the page widget allows you to style a page as a dialog, however, the special navigational handling will be removed. You may also consider implementing dialogs using popup widgets.

Any page can be presented as a modal dialog by adding the data-rel="dialog" attribute to the page anchor link. When the "dialog" attribute is applied, the framework adds styles to add rounded corners, margins around the page and a dark background to make the "dialog" appear to be suspended above the page.

1
<a href="foo.html" data-rel="dialog">Open dialog</a>

You can open a dialog programmatically by calling the $.mobile.changePage method:

1
2
3
4
5
// Dialog loaded via Ajax
$.mobile.changePage( "path/to/dialog.html", { role: "dialog" } );
// Dialog present in a multipage document
$.mobile.changePage( "#myDialog", { role: "dialog" } );

Transitions

By default, the dialog will open with a 'pop' transition. Like all pages, you can specify any page transition you want on the dialog by adding the data-transition attribute to the link. To make it feel more dialog-like, we recommend specifying a transition of "pop", "slidedown" or "flip".
Possible values include: fade, pop, flip, turn, flow, slidefade, slide, slideup, slidedown, none.

1
<a href="foo.html" data-rel="dialog" data-transition="pop">Open dialog</a>

Closing dialogs

When any link is clicked within a dialog, the framework will automatically close the dialog and transition to the requested page, just as if the dialog were a normal page. Nevertheless, dialogs can also be chained, as explained below under "Chaining Dialogs". Similarly, a link that opens a popup will also leave the dialog in place.

If the dialog has a header the framework will add a close button at the left side of the header. You can change the position by adding data-close-btn="right" to the dialog container. If you don't want a close button in the header or add a custom close button, you can use data-close-btn="none".

To create a "cancel" button in a dialog, just link to the page that triggered the dialog to open and add the data-rel="back" attribute to your link. This pattern of linking to the previous page is also usable in non-JS devices as well.

For JavaScript-generated links, you can simply set the href attribute to "#" and use the data-rel="back" attribute. You can also call the dialog's close() method to programmatically close dialogs, for example: $( ".ui-dialog" ).dialog( "close" ).

Setting the close button text

Just like the page plugin, you can set a dialog's close button text through an option or data attribute. The option can be configured for all dialogs by binding to the mobileinit event and setting the $.mobile.dialog.prototype.options.closeBtnText property to a string of your choosing, or you can place the data attribute data-close-btn-text to configure the text from your markup.

History & Back button behavior

Since dialogs are typically used to support actions within a page, the framework does not include dialogs in the hash state history tracking. This means that dialogs will not appear in your browsing history chronology when the Back button is clicked. For example, if you are on a page, click a link to open a dialog, close the dialog, then navigate to another page, if you were to click the browser's Back button at that point you will navigate back to the first page, not the dialog.

Chaining Dialogs

Please note: If a dialog opens another dialog (chaining), closing the last one with a link of type data-rel="back" will always navigate to the previous dialog until the root-page of type data-role="page" is reached. This guarantees a consistent navigation between dialogs.

Styling & theming

Dialogs can be styled with different theme swatches, just like any page by adding data-theme attributes to the header, content, or footer containers.

By default dialogs have rounded corners. The option corners can be set to false by adding data-corners="false" to the dialog container:

Dialogs appear to be floating above an overlay layer. This overlay adopts the swatch 'a' content color by default, but the data-overlay-theme attribute can be added to the page wrapper to set the overlay to any swatch letter.

Dialogs can also be used more like a control sheet to offer multiple buttons if you simply remove the top margin from the dialog's inner container element. For example, if your dialog page had a class of my-dialog, you could add this CSS to pin that dialog to the top: .ui-dialog.my-dialog .ui-dialog-contain { margin-top: 0 }, or you could just apply that style to all dialogs with .ui-dialog .ui-dialog-contain { margin-top: 0 }.

Dialog width and margins

For the sake of readability, dialogs have a default width of 92.5% and a max-width of 500 pixels. There is also a 10% top margin to give dialogs larger top margin on larger screens, but collapse to a small margin on smartphones. The dialog's inner container is shifted towards the top with 15px to hide the corner styling if a dialog is used as a control sheet (see above). To override these styles, add the following CSS override rule to your stylesheet and tweak as needed:

1
2
3
4
5
6
7
8
.ui-dialog-contain {
width: 92.5%;
max-width: 500px;
margin: 10% auto 15px auto;
padding: 0;
position: relative;
top: -15px;
}

Options

closeBtn 

Type: String
Default: "left"

Sets the position of the dialog close button in the header (left or right) or prevents the framework from adding a close button (none).

This option is also exposed as a data attribute: data-close-btn.

Code examples:

Initialize the dialog with the closeBtn option specified:

1
2
3
$( ".selector" ).dialog({
closeBtn: "none"
});

Get or set the closeBtn option, after initialization:

1
2
3
4
5
// Getter
var closeBtn = $( ".selector" ).dialog( "option", "closeBtn" );
// Setter
$( ".selector" ).dialog( "option", "closeBtn", "none" );

closeBtnText 

Type: String
Default: "Close"

Customizes the text of the close button which is helpful for translating this into different languages. The close button is displayed as an icon-only button by default so the text isn't visible on-screen, but is read by screen readers so this is an important accessibility feature.

This option is also exposed as a data attribute: data-close-btn-text="Fermer".

Code examples:

Initialize the dialog with the closeBtnText option specified:

1
2
3
$( ".selector" ).dialog({
closeBtnText: "Fermer"
});

Get or set the closeBtnText option, after initialization:

1
2
3
4
5
// Getter
var closeBtnText = $( ".selector" ).dialog( "option", "closeBtnText" );
// Setter
$( ".selector" ).dialog( "option", "closeBtnText", "Fermer" );

corners 

Type: Boolean
Default: true
Sets whether to draw the dialo with rounded corners..

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

Code examples:

Initialize the dialog with the corners option specified:

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

Get or set the corners option, after initialization:

1
2
3
4
5
// Getter
var corners = $( ".selector" ).dialog( "option", "corners" );
// Setter
$( ".selector" ).dialog( "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 dialog with the defaults option specified:

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

Get or set the defaults option, after initialization:

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

disabled 

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

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

Code examples:

Initialize the dialog with the disabled option specified:

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

Get or set the disabled option, after initialization:

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

initSelector 

Type: Selector
Default: See below

The default initSelector for the dialog widget is:

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

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.dialog.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 dialog widgets on each of the resulting list of elements.

(version deprecated: 1.4.0)

overlayTheme 

Type: String
Default: "a"

Dialogs appear to be floating above an overlay layer. This overlay adopts the swatch A content color by default, but the data-overlay-theme attribute can be added to the page wrapper to set the overlay to any swatch letter.

Possible values: swatch letter (a-z)

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

Code examples:

Initialize the dialog with the overlayTheme option specified:

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

Get or set the overlayTheme option, after initialization:

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

Methods

close()Returns: jQuery (plugin only)

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

Invoke the close method:

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

Events

create( event, ui )Type: dialogcreate

Triggered when a dialog is created

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

Code examples:

Initialize the dialog with the create callback specified:

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

Bind an event listener to the dialogcreate event:

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

Example:

A basic example of opening a page as a dialog by adding data-rel="dialog" to the anchor tag.

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
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>dialog demo</title>
<link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
<script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
<script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.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="#dialogPage" data-rel="dialog">Open dialog</a>
</div>
<div data-role="footer">
<h2></h2>
</div>
</div>
<div data-role="page" id="dialogPage">
<div data-role="header">
<h2>Dialog</h2>
</div>
<div role="main" class="ui-content">
<p>I am a dialog</p>
</div>
</div>
</body>
</html>

Demo: