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
autofocusattribute - The first
:tabbableelement within the dialog's content - The first
:tabbableelement 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 thedraggableoption is set, theui-dialog-draggingclass is added during a drag. If theresizableoption is set, theui-dialog-resizingclass is added during a resize. If thebuttonsoption is set, theui-dialog-buttonsclass 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 thebuttonsoption 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, andeasingproperties may be provided. If theeffectproperty 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. Ifdurationoreasingis omitted, then the default values will be used. Ifeffectis omitted, then"fadeOut"will be used. Ifdelayis 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, andeasingproperties may be provided. If theeffectproperty 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. Ifdurationoreasingis omitted, then the default values will be used. Ifeffectis omitted, then"fadeIn"will be used. Ifdelayis 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>