A dialog is a floating window that contains a title bar and a content area. The dialog window can be moved, resized and closed with the 'x' icon by default.
If the content length exceeds the maximum height, a scrollbar will automatically appear.
A bottom button bar and semi-transparent modal overlay layer are common options that can be added.
Focus
Upon opening a dialog, focus is automatically moved to the first item that matches the following:
- The first element within the dialog with the
autofocus
attribute - The first
:tabbable
element within the dialog's content - The first
:tabbable
element within the dialog's buttonpane - The dialog's close button
- The dialog itself
While open, the dialog widget ensures that keyboard navigation using the 'tab' key causes the focus to cycle amongst the focusable elements in the dialog, not elements outside of it. Modal dialogs additionally prevent mouse users from clicking on elements outside of the dialog.
Upon closing a dialog, focus is automatically returned to the element that had focus when the dialog was opened.
Hiding the close button
In some cases, you may want to hide the close button, for instance, if you have a close button in the button pane. The best way to accomplish this is via CSS. As an example, you can define a simple rule, such as:
.no-close .ui-dialog-titlebar-close { display: none; }
Then, you can simply add the no-close
class to any dialog in order to hide its close button:
$( "#dialog" ).dialog({ dialogClass: "no-close", buttons: [ { text: "OK", click: function() { $( this ).dialog( "close" ); } } ] });
Theming
The dialog widget uses the jQuery UI CSS framework to style its look and feel. If dialog specific styling is needed, the following CSS class names can be used:
-
ui-dialog
: The outer container of the dialog.-
ui-dialog-titlebar
: The title bar containing the dialog's title and close button.-
ui-dialog-title
: The container around the textual title of the dialog. -
ui-dialog-titlebar-close
: The dialog's close button.
-
-
ui-dialog-content
: The container around the dialog's content. This is also the element the widget was instantiated with. -
ui-dialog-buttonpane
: The pane that contains the dialog's buttons. This will only be present if thebuttons
option is set.-
ui-dialog-buttonset
: The container around the buttons themselves.
-
-
Additionally, when the modal
option is set, an element with a ui-widget-overlay
class name is appended to the <body>
.
Dependencies
- UI Core
- Widget Factory
- Position
- Button
- Draggable (optional; for use with the
draggable
option) - Resizable (optional; for use with the
resizable
option) - Effects Core (optional; for use with the
show
andhide
options)
- This widget requires some functional CSS, otherwise it won't work. If you build a custom theme, use the widget's specific CSS file as a starting point.
"body"
Which element the dialog (and overlay, if modal) should be appended to.
appendTo
option should not be changed while the dialog is open.Code examples:
Initialize the dialog with the appendTo
option specified:
$( ".selector" ).dialog({ appendTo: "#someElem" });
Get or set the appendTo
option, after initialization:
// Getter var appendTo = $( ".selector" ).dialog( "option", "appendTo" ); // Setter $( ".selector" ).dialog( "option", "appendTo", "#someElem" );
true
true
, the dialog will automatically open upon initialization. If false
, the dialog will stay hidden until the open()
method is called.Code examples:
Initialize the dialog with the autoOpen
option specified:
$( ".selector" ).dialog({ autoOpen: false });
Get or set the autoOpen
option, after initialization:
// Getter var autoOpen = $( ".selector" ).dialog( "option", "autoOpen" ); // Setter $( ".selector" ).dialog( "option", "autoOpen", false );
[]
Multiple types supported:
- Object: The keys are the button labels and the values are the callbacks for when the associated button is clicked.
- Array: Each element of the array must be an object defining the attributes, properties, and event handlers to set on the button. In addition, a key of
icons
can be used to control button'sicons
option, and a key ofshowText
can be used to control button'stext
option.
Code examples:
Initialize the dialog with the buttons
option specified:
$( ".selector" ).dialog({ buttons: [ { text: "Ok", icons: { primary: "ui-icon-heart" }, click: function() { $( this ).dialog( "close" ); } // Uncommenting the following line would hide the text, // resulting in the label being used as a tooltip //showText: false } ] });
Get or set the buttons
option, after initialization:
// Getter var buttons = $( ".selector" ).dialog( "option", "buttons" ); // Setter $( ".selector" ).dialog( "option", "buttons", [ { text: "Ok", icons: { primary: "ui-icon-heart" }, click: function() { $( this ).dialog( "close" ); } // Uncommenting the following line would hide the text, // resulting in the label being used as a tooltip //showText: false } ] );
true
Code examples:
Initialize the dialog with the closeOnEscape
option specified:
$( ".selector" ).dialog({ closeOnEscape: false });
Get or set the closeOnEscape
option, after initialization:
// Getter var closeOnEscape = $( ".selector" ).dialog( "option", "closeOnEscape" ); // Setter $( ".selector" ).dialog( "option", "closeOnEscape", false );
"close"
Code examples:
Initialize the dialog with the closeText
option specified:
$( ".selector" ).dialog({ closeText: "hide" });
Get or set the closeText
option, after initialization:
// Getter var closeText = $( ".selector" ).dialog( "option", "closeText" ); // Setter $( ".selector" ).dialog( "option", "closeText", "hide" );
""
Code examples:
Initialize the dialog with the dialogClass
option specified:
$( ".selector" ).dialog({ dialogClass: "alert" });
Get or set the dialogClass
option, after initialization:
// Getter var dialogClass = $( ".selector" ).dialog( "option", "dialogClass" ); // Setter $( ".selector" ).dialog( "option", "dialogClass", "alert" );
true
true
, the dialog will be draggable by the title bar. Requires the jQuery UI Draggable widget to be included.Code examples:
Initialize the dialog with the draggable
option specified:
$( ".selector" ).dialog({ draggable: false });
Get or set the draggable
option, after initialization:
// Getter var draggable = $( ".selector" ).dialog( "option", "draggable" ); // Setter $( ".selector" ).dialog( "option", "draggable", false );
"auto"
Multiple types supported:
- Number: The height in pixels.
- String: The only supported string value is
"auto"
which will allow the dialog height to adjust based on its content.
Code examples:
Initialize the dialog with the height
option specified:
$( ".selector" ).dialog({ height: 400 });
Get or set the height
option, after initialization:
// Getter var height = $( ".selector" ).dialog( "option", "height" ); // Setter $( ".selector" ).dialog( "option", "height", 400 );
null
Multiple types supported:
- Boolean: When set to
false
, no animation will be used and the dialog will be hidden immediately. When set totrue
, the dialog will fade out with the default duration and the default easing. - Number: The dialog will fade out with the specified duration and the default easing.
- String: The dialog will be hidden using the specified effect. The value can either be the name of a built-in jQuery animation method, such as
"slideUp"
, or the name of a jQuery UI effect, such as"fold"
. In either case the effect will be used with the default duration and the default easing. - Object: If the value is an object, then
effect
,delay
,duration
, andeasing
properties may be provided. If theeffect
property contains the name of a jQuery method, then that method will be used; otherwise it is assumed to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you may include those settings in the object and they will be passed to the effect. Ifduration
oreasing
is omitted, then the default values will be used. Ifeffect
is omitted, then"fadeOut"
will be used. Ifdelay
is omitted, then no delay is used.
Code examples:
Initialize the dialog with the hide
option specified:
$( ".selector" ).dialog({ hide: { effect: "explode", duration: 1000 } });
Get or set the hide
option, after initialization:
// Getter var hide = $( ".selector" ).dialog( "option", "hide" ); // Setter $( ".selector" ).dialog( "option", "hide", { effect: "explode", duration: 1000 } );
false
Code examples:
Initialize the dialog with the maxHeight
option specified:
$( ".selector" ).dialog({ maxHeight: 600 });
Get or set the maxHeight
option, after initialization:
// Getter var maxHeight = $( ".selector" ).dialog( "option", "maxHeight" ); // Setter $( ".selector" ).dialog( "option", "maxHeight", 600 );
false
Code examples:
Initialize the dialog with the maxWidth
option specified:
$( ".selector" ).dialog({ maxWidth: 600 });
Get or set the maxWidth
option, after initialization:
// Getter var maxWidth = $( ".selector" ).dialog( "option", "maxWidth" ); // Setter $( ".selector" ).dialog( "option", "maxWidth", 600 );
150
Code examples:
Initialize the dialog with the minHeight
option specified:
$( ".selector" ).dialog({ minHeight: 200 });
Get or set the minHeight
option, after initialization:
// Getter var minHeight = $( ".selector" ).dialog( "option", "minHeight" ); // Setter $( ".selector" ).dialog( "option", "minHeight", 200 );
150
Code examples:
Initialize the dialog with the minWidth
option specified:
$( ".selector" ).dialog({ minWidth: 200 });
Get or set the minWidth
option, after initialization:
// Getter var minWidth = $( ".selector" ).dialog( "option", "minWidth" ); // Setter $( ".selector" ).dialog( "option", "minWidth", 200 );
false
true
, the dialog will have modal behavior; other items on the page will be disabled, i.e., cannot be interacted with. Modal dialogs create an overlay below the dialog but above other page elements.Code examples:
Initialize the dialog with the modal
option specified:
$( ".selector" ).dialog({ modal: true });
Get or set the modal
option, after initialization:
// Getter var modal = $( ".selector" ).dialog( "option", "modal" ); // Setter $( ".selector" ).dialog( "option", "modal", true );
{ my: "center", at: "center", of: window }
Specifies where the dialog should be displayed when opened. The dialog will handle collisions such that as much of the dialog is visible as possible.
The of
property defaults to the window, but you can specify another element to position against. You can refer to the jQuery UI Position utility for more details about the available properties.
Code examples:
Initialize the dialog with the position
option specified:
$( ".selector" ).dialog({ position: { my: "left top", at: "left bottom", of: button } });
Get or set the position
option, after initialization:
// Getter var position = $( ".selector" ).dialog( "option", "position" ); // Setter $( ".selector" ).dialog( "option", "position", { my: "left top", at: "left bottom", of: button } );
true
true
, the dialog will be resizable. Requires the jQuery UI Resizable widget to be included.Code examples:
Initialize the dialog with the resizable
option specified:
$( ".selector" ).dialog({ resizable: false });
Get or set the resizable
option, after initialization:
// Getter var resizable = $( ".selector" ).dialog( "option", "resizable" ); // Setter $( ".selector" ).dialog( "option", "resizable", false );
null
Multiple types supported:
- Boolean: When set to
false
, no animation will be used and the dialog will be shown immediately. When set totrue
, the dialog will fade in with the default duration and the default easing. - Number: The dialog will fade in with the specified duration and the default easing.
- String: The dialog will be shown using the specified effect. The value can either be the name of a built-in jQuery animation method, such as
"slideDown"
, or the name of a jQuery UI effect, such as"fold"
. In either case the effect will be used with the default duration and the default easing. - Object: If the value is an object, then
effect
,delay
,duration
, andeasing
properties may be provided. If theeffect
property contains the name of a jQuery method, then that method will be used; otherwise it is assumed to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you may include those settings in the object and they will be passed to the effect. Ifduration
oreasing
is omitted, then the default values will be used. Ifeffect
is omitted, then"fadeIn"
will be used. Ifdelay
is omitted, then no delay is used.
Code examples:
Initialize the dialog with the show
option specified:
$( ".selector" ).dialog({ show: { effect: "blind", duration: 800 } });
Get or set the show
option, after initialization:
// Getter var show = $( ".selector" ).dialog( "option", "show" ); // Setter $( ".selector" ).dialog( "option", "show", { effect: "blind", duration: 800 } );
null
null
, the title
attribute on the dialog source element will be used.Code examples:
Initialize the dialog with the title
option specified:
$( ".selector" ).dialog({ title: "Dialog Title" });
Get or set the title
option, after initialization:
// Getter var title = $( ".selector" ).dialog( "option", "title" ); // Setter $( ".selector" ).dialog( "option", "title", "Dialog Title" );
300
Code examples:
Initialize the dialog with the width
option specified:
$( ".selector" ).dialog({ width: 500 });
Get or set the width
option, after initialization:
// Getter var width = $( ".selector" ).dialog( "option", "width" ); // Setter $( ".selector" ).dialog( "option", "width", 500 );
- This method does not accept any arguments.
Invoke the close method:
$( ".selector" ).dialog( "close" );
- This method does not accept any arguments.
Invoke the destroy method:
$( ".selector" ).dialog( "destroy" );
Retrieves the dialog's instance object. If the element does not have an associated instance, undefined
is returned.
Unlike other widget methods, instance()
is safe to call on any element after the dialog plugin has loaded.
- This method does not accept any arguments.
Invoke the instance method:
$( ".selector" ).dialog( "instance" );
- This method does not accept any arguments.
Invoke the isOpen method:
var isOpen = $( ".selector" ).dialog( "isOpen" );
- This method does not accept any arguments.
Invoke the moveToTop method:
$( ".selector" ).dialog( "moveToTop" );
- This method does not accept any arguments.
Invoke the open method:
$( ".selector" ).dialog( "open" );
Gets the value currently associated with the specified optionName
.
Note: For options that have objects as their value, you can get the value of a specific key by using dot notation. For example, "foo.bar"
would get the value of the bar
property on the foo
option.
- optionNameType: StringThe name of the option to get.
Invoke the method:
var isDisabled = $( ".selector" ).dialog( "option", "disabled" );
- This signature does not accept any arguments.
Invoke the method:
var options = $( ".selector" ).dialog( "option" );
Sets the value of the dialog option associated with the specified optionName
.
Note: For options that have objects as their value, you can set the value of just one property by using dot notation for optionName
. For example, "foo.bar"
would update only the bar
property of the foo
option.
- optionNameType: StringThe name of the option to set.
- valueType: ObjectA value to set for the option.
Invoke the method:
$( ".selector" ).dialog( "option", "disabled", true );
- optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
$( ".selector" ).dialog( "option", { disabled: true } );
jQuery
object containing the generated wrapper. - This method does not accept any arguments.
Invoke the widget method:
var widget = $( ".selector" ).dialog( "widget" );
_allowInteraction()
method determines whether the user should be allowed to interact with a given target element; therefore, it can be used to whitelist elements that are not children of the dialog but you want users to be able to use. - eventType: Event
Allow the Select2 plugin to be used within modal dialogs. The _super()
call ensures elements within the dialog can still be interacted with.
_allowInteraction: function( event ) { return !!$( event.target ).is( ".select2-input" ) || this._super( event ); }
dialogbeforeclose
Note: The ui
object is empty but included for consistency with other events.
Initialize the dialog with the beforeClose callback specified:
$( ".selector" ).dialog({ beforeClose: function( event, ui ) {} });
Bind an event listener to the dialogbeforeclose event:
$( ".selector" ).on( "dialogbeforeclose", function( event, ui ) {} );
dialogclose
Note: The ui
object is empty but included for consistency with other events.
Initialize the dialog with the close callback specified:
$( ".selector" ).dialog({ close: function( event, ui ) {} });
Bind an event listener to the dialogclose event:
$( ".selector" ).on( "dialogclose", function( event, ui ) {} );
dialogcreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the dialog with the create callback specified:
$( ".selector" ).dialog({ create: function( event, ui ) {} });
Bind an event listener to the dialogcreate event:
$( ".selector" ).on( "dialogcreate", function( event, ui ) {} );
dialogdrag
Initialize the dialog with the drag callback specified:
$( ".selector" ).dialog({ drag: function( event, ui ) {} });
Bind an event listener to the dialogdrag event:
$( ".selector" ).on( "dialogdrag", function( event, ui ) {} );
dialogdragstart
Initialize the dialog with the dragStart callback specified:
$( ".selector" ).dialog({ dragStart: function( event, ui ) {} });
Bind an event listener to the dialogdragstart event:
$( ".selector" ).on( "dialogdragstart", function( event, ui ) {} );
dialogdragstop
Initialize the dialog with the dragStop callback specified:
$( ".selector" ).dialog({ dragStop: function( event, ui ) {} });
Bind an event listener to the dialogdragstop event:
$( ".selector" ).on( "dialogdragstop", function( event, ui ) {} );
dialogfocus
Note: The ui
object is empty but included for consistency with other events.
Initialize the dialog with the focus callback specified:
$( ".selector" ).dialog({ focus: function( event, ui ) {} });
Bind an event listener to the dialogfocus event:
$( ".selector" ).on( "dialogfocus", function( event, ui ) {} );
dialogopen
Note: The ui
object is empty but included for consistency with other events.
Initialize the dialog with the open callback specified:
$( ".selector" ).dialog({ open: function( event, ui ) {} });
Bind an event listener to the dialogopen event:
$( ".selector" ).on( "dialogopen", function( event, ui ) {} );
dialogresize
Initialize the dialog with the resize callback specified:
$( ".selector" ).dialog({ resize: function( event, ui ) {} });
Bind an event listener to the dialogresize event:
$( ".selector" ).on( "dialogresize", function( event, ui ) {} );
dialogresizestart
Initialize the dialog with the resizeStart callback specified:
$( ".selector" ).dialog({ resizeStart: function( event, ui ) {} });
Bind an event listener to the dialogresizestart event:
$( ".selector" ).on( "dialogresizestart", function( event, ui ) {} );
dialogresizestop
Initialize the dialog with the resizeStop callback specified:
$( ".selector" ).dialog({ resizeStop: function( event, ui ) {} });
Bind an event listener to the dialogresizestop event:
$( ".selector" ).on( "dialogresizestop", function( event, ui ) {} );
A simple jQuery UI Dialog
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>dialog demo</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css"> <script src="//code.jquery.com/jquery-1.10.2.js"></script> <script src="//code.jquery.com/ui/1.11.4/jquery-ui.js"></script> </head> <body> <button id="opener">open the dialog</button> <div id="dialog" title="Dialog Title">I'm a dialog</div> <script> $( "#dialog" ).dialog({ autoOpen: false }); $( "#opener" ).click(function() { $( "#dialog" ).dialog( "open" ); }); </script> </body> </html>
Please login to continue.