## Dialog Widget version added: 1.0

Description: Open content in an interactive overlay.

## QuickNavExamples

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.

### 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` and `hide` options)

### 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

### autoOpenType: 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

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

Get or set the `autoOpen` option, after initialization:

1
2
3
4
5

    // gettervar autoOpen = $( ".selector" ).dialog( "option", "autoOpen" ); // setter$( ".selector" ).dialog( "option", "autoOpen", false );

### buttonsType: 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

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

Get or set the `buttons` option, after initialization:

1
2
3
4
5

    // gettervar buttons = $( ".selector" ).dialog( "option", "buttons" ); // setter$( ".selector" ).dialog( "option", "buttons", [ { text: "Ok", click: function() { $( this ).dialog( "close" ); } } ] );

### closeOnEscapeType: 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

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

Get or set the `closeOnEscape` option, after initialization:

1
2
3
4
5

    // gettervar closeOnEscape = $( ".selector" ).dialog( "option", "closeOnEscape" ); // setter$( ".selector" ).dialog( "option", "closeOnEscape", false );

### closeTextType: 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

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

Get or set the `closeText` option, after initialization:

1
2
3
4
5

    // gettervar closeText = $( ".selector" ).dialog( "option", "closeText" ); // setter$( ".selector" ).dialog( "option", "closeText", "hide" );

### dialogClassType: 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

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

Get or set the `dialogClass` option, after initialization:

1
2
3
4
5

    // gettervar dialogClass = $( ".selector" ).dialog( "option", "dialogClass" ); // setter$( ".selector" ).dialog( "option", "dialogClass", "alert" );

### draggableType: Boolean

Default: `true`
If set to `true`, the dialog will be draggable by the title bar. Requires the jQuery UI Draggable wiget to be included.
Code examples:

Initialize the dialog with the `draggable` option specified:

1

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

Get or set the `draggable` option, after initialization:

1
2
3
4
5

    // gettervar draggable = $( ".selector" ).dialog( "option", "draggable" ); // setter$( ".selector" ).dialog( "option", "draggable", false );

### heightType: 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

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

Get or set the `height` option, after initialization:

1
2
3
4
5

    // gettervar height = $( ".selector" ).dialog( "option", "height" ); // setter$( ".selector" ).dialog( "option", "height", 400 );

### hideType: Number or String or Object

Default: `null`
If and how to animate the hiding of the dialog.
Multiple types supported:

- Number: The dialog will fade out while animating the height and width for the specified duration.
- String: The dialog will be hidden using the specified jQuery UI effect. See the list of effects for possible values.
- Object: If the value is an object, then `effect`, `duration`, and `easing` properties may be provided. The `effect` property must 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.

Code examples:

Initialize the dialog with the `hide` option specified:

1

    $( ".selector" ).dialog({ hide: "explode" });

Get or set the `hide` option, after initialization:

1
2
3
4
5

    // gettervar hide = $( ".selector" ).dialog( "option", "hide" ); // setter$( ".selector" ).dialog( "option", "hide", "explode" );

### maxHeightType: 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

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

Get or set the `maxHeight` option, after initialization:

1
2
3
4
5

    // gettervar maxHeight = $( ".selector" ).dialog( "option", "maxHeight" ); // setter$( ".selector" ).dialog( "option", "maxHeight", 600 );

### maxWidthType: 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

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

Get or set the `maxWidth` option, after initialization:

1
2
3
4
5

    // gettervar maxWidth = $( ".selector" ).dialog( "option", "maxWidth" ); // setter$( ".selector" ).dialog( "option", "maxWidth", 600 );

### minHeightType: 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

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

Get or set the `minHeight` option, after initialization:

1
2
3
4
5

    // gettervar minHeight = $( ".selector" ).dialog( "option", "minHeight" ); // setter$( ".selector" ).dialog( "option", "minHeight", 200 );

### minWidthType: 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

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

Get or set the `minWidth` option, after initialization:

1
2
3
4
5

    // gettervar minWidth = $( ".selector" ).dialog( "option", "minWidth" ); // setter$( ".selector" ).dialog( "option", "minWidth", 200 );

### modalType: 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

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

Get or set the `modal` option, after initialization:

1
2
3
4
5

    // gettervar modal = $( ".selector" ).dialog( "option", "modal" ); // setter$( ".selector" ).dialog( "option", "modal", true );

### positionType: 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.
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

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

Get or set the `position` option, after initialization:

1
2
3
4
5

    // gettervar position = $( ".selector" ).dialog( "option", "position" ); // setter$( ".selector" ).dialog( "option", "position", { my: "left top", at: "left bottom", of: button } );

### resizableType: 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

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

Get or set the `resizable` option, after initialization:

1
2
3
4
5

    // gettervar resizable = $( ".selector" ).dialog( "option", "resizable" ); // setter$( ".selector" ).dialog( "option", "resizable", false );

### showType: Number or String or Object

Default: `null`
If and how to animate the showing of the dialog.
Multiple types supported:

- Number: The dialog will fade in while animating the height and width for the specified duration.
- String: The dialog will be shown using the specified jQuery UI effect. See the list of effects for possible values.
- Object: If the value is an object, then `effect`, `duration`, and `easing` properties may be provided. The `effect` property must 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.

Code examples:

Initialize the dialog with the `show` option specified:

1

    $( ".selector" ).dialog({ show: "slow" });

Get or set the `show` option, after initialization:

1
2
3
4
5

    // gettervar show = $( ".selector" ).dialog( "option", "show" ); // setter$( ".selector" ).dialog( "option", "show", "slow" );

### stackType: Boolean

Default: `true`
Specifies whether the dialog will stack on top of other dialogs. This will cause the dialog to move to the front of other dialogs when it gains focus.
Code examples:

Initialize the dialog with the `stack` option specified:

1

    $( ".selector" ).dialog({ stack: false });

Get or set the `stack` option, after initialization:

1
2
3
4
5

    // gettervar stack = $( ".selector" ).dialog( "option", "stack" ); // setter$( ".selector" ).dialog( "option", "stack", false );

### titleType: String

Default: `""`
Specifies the title of the dialog. Any valid HTML may be set as the title. The title can also be specified by the `title` attribute on the dialog source element.
Code examples:

Initialize the dialog with the `title` option specified:

1

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

Get or set the `title` option, after initialization:

1
2
3
4
5

    // gettervar title = $( ".selector" ).dialog( "option", "title" ); // setter$( ".selector" ).dialog( "option", "title", "Dialog Title" );

### widthType: Number

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

Initialize the dialog with the `width` option specified:

1

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

Get or set the `width` option, after initialization:

1
2
3
4
5

    // gettervar width = $( ".selector" ).dialog( "option", "width" ); // setter$( ".selector" ).dialog( "option", "width", 500 );

### zIndexType: Integer

Default: `1000`
The starting z-index for the dialog.
Code examples:

Initialize the dialog with the `zIndex` option specified:

1

    $( ".selector" ).dialog({ zIndex: 20 });

Get or set the `zIndex` option, after initialization:

1
2
3
4
5

    // gettervar zIndex = $( ".selector" ).dialog( "option", "zIndex" ); // setter$( ".selector" ).dialog( "option", "zIndex", 20 );

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

## Events

### beforeClose( event, ui )Type: `dialogbeforeclose`

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

- event
  Type: Event
- ui
  Type: Object

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.

- event
  Type: Event
- ui
  Type: Object

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.

- event
  Type: Event
- ui
  Type: Object

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.

- event
  Type: Event
- ui
  Type: Object

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.

- event
  Type: Event
- ui
  Type: Object

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.9.2/themes/base/jquery-ui.css">  <script src="//code.jquery.com/jquery-1.8.3.js"></script>  <script src="//code.jquery.com/ui/1.9.2/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: