Dialog Widgetversion added: 1.0
Description: Open content in an interactive overlay.
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 for overrides or as keys for the classes
option:
-
ui-dialog
: The outer container of the dialog. If thedraggable
option is set, theui-dialog-dragging
class is added during a drag. If theresizable
option is set, theui-dialog-resizing
class is added during a resize. If thebuttons
option is set, theui-dialog-buttons
class is added.-
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
Additional Notes:
- 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.
Options
appendTo
"body"
Which element the dialog (and overlay, if modal) should be appended to.
appendTo
option should not be changed while the dialog is open.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" );
autoOpen
true
true
, the dialog will automatically open upon initialization. If false
, the dialog will stay hidden until the open()
method is called.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 );
classes
{ "ui-dialog": "ui-corner-all", "ui-dialog-titlebar": "ui-corner-all", }
Specify additional classes to add to the widget's elements. Any of classes specified in the Theming section can be used as keys to override their value. To learn more about this option, check out the learn article about the classes
option.
Initialize the dialog with the classes
option specified, changing the theming for the ui-dialog
class:
$( ".selector" ).dialog({ classes: { "ui-dialog": "highlight" } });
Get or set a property of the classes
option, after initialization, here reading and changing the theming for the ui-dialog
class:
// Getter var themeClass = $( ".selector" ).dialog( "option", "classes.ui-dialog" ); // Setter $( ".selector" ).dialog( "option", "classes.ui-dialog", "highlight" );
closeOnEscape
true
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 );
closeText
"close"
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" );
dialogClass
""
The specified class name(s) will be added to the dialog, for additional theming.
The dialogClass
option has been deprecated in favor of the classes
option, using the ui-dialog
property.
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" );
draggable
true
true
, the dialog will be draggable by the title bar. Requires the jQuery UI Draggable widget to be included.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 );
height
"auto"
- 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.
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 );
hide
null
- 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.
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 } );
maxHeight
false
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 );
maxWidth
false
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 );
minHeight
150
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 );
minWidth
150
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 );
modal
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.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 );
position
{ 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.
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 } );
resizable
true
true
, the dialog will be resizable. Requires the jQuery UI Resizable widget to be included.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 );
show
null
- 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.
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 } );
title
null
null
, the title
attribute on the dialog source element will be used.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" );
width
300
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 );
Methods
close()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the close method:
$( ".selector" ).dialog( "close" );
destroy()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the destroy method:
$( ".selector" ).dialog( "destroy" );
instance()Returns: Object
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" );
isOpen()Returns: Boolean
- This method does not accept any arguments.
Invoke the isOpen method:
var isOpen = $( ".selector" ).dialog( "isOpen" );
moveToTop()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the moveToTop method:
$( ".selector" ).dialog( "moveToTop" );
open()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the open method:
$( ".selector" ).dialog( "open" );
option( optionName )Returns: Object
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" );
option()Returns: PlainObject
- This signature does not accept any arguments.
Invoke the method:
var options = $( ".selector" ).dialog( "option" );
option( optionName, value )Returns: jQuery (plugin only)
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 );
option( options )Returns: jQuery (plugin only)
- optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
$( ".selector" ).dialog( "option", { disabled: true } );
widget()Returns: jQuery
jQuery
object containing the generated wrapper. - This method does not accept any arguments.
Invoke the widget method:
var widget = $( ".selector" ).dialog( "widget" );
Extension Points
The dialog widget is built with the widget factory and can be extended. When extending widgets, you have the ability to override or add to the behavior of existing methods. The following methods are provided as extension points with the same API stability as the plugin methods listed above. For more information on widget extensions, see Extending Widgets with the Widget Factory.
_allowInteraction( event )Returns: Boolean
_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 ); }
Events
beforeClose( event, ui )Type: 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 ) {} );
close( event, ui )Type: 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 ) {} );
create( event, ui )Type: 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 ) {} );
drag( event, ui )Type: 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 ) {} );
dragStart( event, ui )Type: 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 ) {} );
dragStop( event, ui )Type: 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 ) {} );
focus( event, ui )Type: 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 ) {} );
open( event, ui )Type: 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 ) {} );
resize( event, ui )Type: 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 ) {} );
resizeStart( event, ui )Type: 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 ) {} );
resizeStop( event, ui )Type: 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 ) {} );
Example:
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.12.1/themes/smoothness/jquery-ui.css"> <script src="//code.jquery.com/jquery-1.12.4.js"></script> <script src="//code.jquery.com/ui/1.12.1/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>