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:
-
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 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
- UI Core
- Widget Factory
- Position
- Button
- Draggable (optional; for use with the
draggableoption) - Resizable (optional; for use with the
resizableoption) - Effects Core (optional; for use with the
showandhideoptions)
- 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
iconscan be used to control button'siconsoption, and a key ofshowTextcan be used to control button'stextoption.
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, 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.
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, 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.
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.