Dialog Widget

Categories: Widgets

Dialog Widgetversion added: 1.0

Description: Open content in an interactive overlay.

QuickNavExamples

Options

Methods


Extension Points

Events

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:

  1. The first element within the dialog with the autofocus attribute
  2. The first :tabbable element within the dialog's content
  3. The first :tabbable element within the dialog's buttonpane
  4. The dialog's close button
  5. The dialog itself

While open, the dialog widget ensures that tabbing cycles focus between elements within the dialog itself, 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:

1
2
3
 
.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:

1
2
3
4
5
6
7
8
9
10
11
 
$( "#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 the buttons 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 

Type: Selector
Default: "body"

Which element the dialog (and overlay, if modal) should be appended to.

Note: The appendTo option should not be changed while the dialog is open.
(version added: 1.10.0)
Code examples:

Initialize the dialog with the appendTo option specified:

1
2
3
 
$( ".selector" ).dialog({
  appendTo: "#someElem"
});

Get or set the appendTo option, after initialization:

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

autoOpen 

Type: Boolean
Default: true
If set to 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:

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

Get or set the autoOpen option, after initialization:

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

buttons 

Type: Object or Array
Default: {}
Specifies which buttons should be displayed on the dialog. The context of the callback is the dialog element; if you need access to the button, it is available as the target of the event object.
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.
Code examples:

Initialize the dialog with the buttons option specified:

1
2
3
 
$( ".selector" ).dialog({
  buttons: [ { text: "Ok", click: function() { $( this ).dialog( "close" ); } } ]
});

Get or set the buttons option, after initialization:

1
2
3
4
5
 
// Getter
var buttons = $( ".selector" ).dialog( "option", "buttons" );
 
// Setter
$( ".selector" ).dialog( "option", "buttons", [ { text: "Ok", click: function() { $( this ).dialog( "close" ); } } ] );

closeOnEscape 

Type: Boolean
Default: true
Specifies whether the dialog should close when it has focus and the user presses the escape (ESC) key.
Code examples:

Initialize the dialog with the closeOnEscape option specified:

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

Get or set the closeOnEscape option, after initialization:

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

closeText 

Type: String
Default: "close"
Specifies the text for the close button. Note that the close text is visibly hidden when using a standard theme.
Code examples:

Initialize the dialog with the closeText option specified:

1
2
3
 
$( ".selector" ).dialog({
  closeText: "hide"
});

Get or set the closeText option, after initialization:

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

dialogClass 

Type: String
Default: ""
The specified class name(s) will be added to the dialog, for additional theming.
Code examples:

Initialize the dialog with the dialogClass option specified:

1
2
3
 
$( ".selector" ).dialog({
  dialogClass: "alert"
});

Get or set the dialogClass option, after initialization:

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

draggable 

Type: Boolean
Default: true
If set to 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:

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

Get or set the draggable option, after initialization:

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

height 

Type: Number or String
Default: "auto"
The height of the dialog.
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:

1
2
3
 
$( ".selector" ).dialog({
  height: 400
});

Get or set the height option, after initialization:

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

hide 

Type: Boolean or Number or String or Object
Default: null
If and how to animate the hiding of the dialog.
Multiple types supported:
  • Boolean: When set to false, no animation will be used and the dialog will be hidden immediately. When set to true, 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, and easing properties may be provided. If the effect 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. If duration or easing is omitted, then the default values will be used. If effect is omitted, then "fadeOut" will be used. If delay is omitted, then no delay is used.
Code examples:

Initialize the dialog with the hide option specified:

1
2
3
 
$( ".selector" ).dialog({
  hide: { effect: "explode", duration: 1000 }
});

Get or set the hide option, after initialization:

1
2
3
4
5
 
// Getter
var hide = $( ".selector" ).dialog( "option", "hide" );
 
// Setter
$( ".selector" ).dialog( "option", "hide", { effect: "explode", duration: 1000 } );

maxHeight 

Type: Number
Default: false
The maximum height to which the dialog can be resized, in pixels.
Code examples:

Initialize the dialog with the maxHeight option specified:

1
2
3
 
$( ".selector" ).dialog({
  maxHeight: 600
});

Get or set the maxHeight option, after initialization:

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

maxWidth 

Type: Number
Default: false
The maximum width to which the dialog can be resized, in pixels.
Code examples:

Initialize the dialog with the maxWidth option specified:

1
2
3
 
$( ".selector" ).dialog({
  maxWidth: 600
});

Get or set the maxWidth option, after initialization:

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

minHeight 

Type: Number
Default: 150
The minimum height to which the dialog can be resized, in pixels.
Code examples:

Initialize the dialog with the minHeight option specified:

1
2
3
 
$( ".selector" ).dialog({
  minHeight: 200
});

Get or set the minHeight option, after initialization:

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

minWidth 

Type: Number
Default: 150
The minimum width to which the dialog can be resized, in pixels.
Code examples:

Initialize the dialog with the minWidth option specified:

1
2
3
 
$( ".selector" ).dialog({
  minWidth: 200
});

Get or set the minWidth option, after initialization:

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

modal 

Type: Boolean
Default: false
If set to 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:

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

Get or set the modal option, after initialization:

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

position 

Type: Object or String or Array
Default: { my: "center", at: "center", of: window }

Specifies where the dialog should be displayed. The dialog will handle collisions such that as much of the dialog is visible as possible.

Note: The String and Array forms are deprecated.

Multiple types supported:
  • Object: Identifies the position of the dialog when opened. The of option 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 various options.
  • String: A string representing the position within the viewport. Possible values: "center", "left", "right", "top", "bottom".
  • Array: An array containing an x, y coordinate pair in pixel offset from the top left corner of the viewport or the name of a possible string value.
Code examples:

Initialize the dialog with the position option specified:

1
2
3
 
$( ".selector" ).dialog({
  position: { my: "left top", at: "left bottom", of: button }
});

Get or set the position option, after initialization:

1
2
3
4
5
 
// Getter
var position = $( ".selector" ).dialog( "option", "position" );
 
// Setter
$( ".selector" ).dialog( "option", "position", { my: "left top", at: "left bottom", of: button } );

resizable 

Type: Boolean
Default: true
If set to 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:

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

Get or set the resizable option, after initialization:

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

show 

Type: Boolean or Number or String or Object
Default: null
If and how to animate the showing of the dialog.
Multiple types supported:
  • Boolean: When set to false, no animation will be used and the dialog will be shown immediately. When set to true, 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, and easing properties may be provided. If the effect 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. If duration or easing is omitted, then the default values will be used. If effect is omitted, then "fadeIn" will be used. If delay is omitted, then no delay is used.
Code examples:

Initialize the dialog with the show option specified:

1
2
3
 
$( ".selector" ).dialog({
  show: { effect: "blind", duration: 800 }
});

Get or set the show option, after initialization:

1
2
3
4
5
 
// Getter
var show = $( ".selector" ).dialog( "option", "show" );
 
// Setter
$( ".selector" ).dialog( "option", "show", { effect: "blind", duration: 800 } );

title 

Type: String
Default: null
Specifies the title of the dialog. If the value is null, the title attribute on the dialog source element will be used.
Code examples:

Initialize the dialog with the title option specified:

1
2
3
 
$( ".selector" ).dialog({
  title: "Dialog Title"
});

Get or set the title option, after initialization:

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

width 

Type: Number
Default: 300
The width of the dialog, in pixels.
Code examples:

Initialize the dialog with the width option specified:

1
2
3
 
$( ".selector" ).dialog({
  width: 500
});

Get or set the width option, after initialization:

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

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" );

destroy()Returns: jQuery (plugin only)

Removes the dialog functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

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

isOpen()Returns: Boolean

Whether the dialog is currently open.
  • This method does not accept any arguments.
Code examples:

Invoke the isOpen method:

1
 
var isOpen = $( ".selector" ).dialog( "isOpen" );

moveToTop()Returns: jQuery (plugin only)

Moves the dialog to the top of the dialog stack.
  • This method does not accept any arguments.
Code examples:

Invoke the moveToTop method:

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

open()Returns: jQuery (plugin only)

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

Invoke the open method:

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

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
 
var isDisabled = $( ".selector" ).dialog( "option", "disabled" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current dialog options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
var options = $( ".selector" ).dialog( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the dialog option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
 
$( ".selector" ).dialog( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the dialog.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

1
 
$( ".selector" ).dialog( "option", { disabled: true } );

widget()Returns: jQuery

Returns a jQuery object containing the generated wrapper.
  • This method does not accept any arguments.
Code examples:

Invoke the widget method:

1
 
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

Modal dialogs do not allow users to interact with elements behind the dialog. This can be problematic for elements that are not children of the dialog, but are absolutely positioned to appear as though they are. The _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.
Code examples:

Allow the Select2 plugin to be used within modal dialogs. The _super() call ensures elements within the dialog can still be interacted with.

1
2
3
 
_allowInteraction: function( event ) {
  return !!$( event.target ).is( ".select2-input" ) || this._super( event );
}

Events

beforeClose( event, ui )Type: dialogbeforeclose

Triggered when a dialog is about to close. If canceled, the dialog will not close.

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

Code examples:

Initialize the dialog with the beforeClose callback specified:

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

Bind an event listener to the dialogbeforeclose event:

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

close( event, ui )Type: dialogclose

Triggered when the dialog is closed.

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

Code examples:

Initialize the dialog with the close callback specified:

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

Bind an event listener to the dialogclose event:

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

create( event, ui )Type: dialogcreate

Triggered when the 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 ) {} );

drag( event, ui )Type: dialogdrag

Triggered while the dialog is being dragged.
  • event
    Type: Event
  • ui
    Type: Object
    • position
      Type: Object
      The current CSS position of the dialog.
    • offset
      Type: Object
      The current offset position of the dialog.
Code examples:

Initialize the dialog with the drag callback specified:

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

Bind an event listener to the dialogdrag event:

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

dragStart( event, ui )Type: dialogdragstart

Triggered when the user starts dragging the dialog.
  • event
    Type: Event
  • ui
    Type: Object
    • position
      Type: Object
      The current CSS position of the dialog.
    • offset
      Type: Object
      The current offset position of the dialog.
Code examples:

Initialize the dialog with the dragStart callback specified:

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

Bind an event listener to the dialogdragstart event:

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

dragStop( event, ui )Type: dialogdragstop

Triggered after the dialog has been dragged.
  • event
    Type: Event
  • ui
    Type: Object
    • position
      Type: Object
      The current CSS position of the dialog.
    • offset
      Type: Object
      The current offset position of the dialog.
Code examples:

Initialize the dialog with the dragStop callback specified:

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

Bind an event listener to the dialogdragstop event:

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

focus( event, ui )Type: dialogfocus

Triggered when the dialog gains focus.

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

Code examples:

Initialize the dialog with the focus callback specified:

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

Bind an event listener to the dialogfocus event:

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

open( event, ui )Type: dialogopen

Triggered when the dialog is opened.

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

Code examples:

Initialize the dialog with the open callback specified:

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

Bind an event listener to the dialogopen event:

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

resize( event, ui )Type: dialogresize

Triggered while the dialog is being resized.
  • event
    Type: Event
  • ui
    Type: Object
    • originalPosition
      Type: Object
      The CSS position of the dialog prior to being resized.
    • position
      Type: Object
      The current CSS position of the dialog.
    • originalSize
      Type: Object
      The size of the dialog prior to being resized.
    • size
      Type: Object
      The current size of the dialog.
Code examples:

Initialize the dialog with the resize callback specified:

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

Bind an event listener to the dialogresize event:

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

resizeStart( event, ui )Type: dialogresizestart

Triggered when the user starts resizing the dialog.
  • event
    Type: Event
  • ui
    Type: Object
    • originalPosition
      Type: Object
      The CSS position of the dialog prior to being resized.
    • position
      Type: Object
      The current CSS position of the dialog.
    • originalSize
      Type: Object
      The size of the dialog prior to being resized.
    • size
      Type: Object
      The current size of the dialog.
Code examples:

Initialize the dialog with the resizeStart callback specified:

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

Bind an event listener to the dialogresizestart event:

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

resizeStop( event, ui )Type: dialogresizestop

Triggered after the dialog has been resized.
  • event
    Type: Event
  • ui
    Type: Object
    • originalPosition
      Type: Object
      The CSS position of the dialog prior to being resized.
    • position
      Type: Object
      The current CSS position of the dialog.
    • originalSize
      Type: Object
      The size of the dialog prior to being resized.
    • size
      Type: Object
      The current size of the dialog.
Code examples:

Initialize the dialog with the resizeStop callback specified:

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

Bind an event listener to the dialogresizestop event:

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

Example:

A simple jQuery UI Dialog

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>dialog demo</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
  <script src="//code.jquery.com/jquery-1.10.2.js"></script>
  <script src="//code.jquery.com/ui/1.10.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>

Demo: