## Dialog Widget version added: 1.0

Description: Open content in an interactive overlay.

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

`$(` `".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` `);`

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

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

Get or set the buttons option, after initialization:

`// getter` `var` `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 esacpe (ESC) key.
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` `);`

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

`$(` `".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"` `);`

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

`$(` `".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"` `);`

### disabledType: Boolean

Default: `false`
Disables the dialog if set to `true`.
Code examples:

Initialize the dialog with the disabled option specified:

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

Get or set the disabled option, after initialization:

`// getter` `var` `disabled = $(` `".selector"` `).dialog(` `"option"``,` `"disabled"` `);` `// setter` `$(` `".selector"` `).dialog(` `"option"``,` `"disabled"``,` `true` `);`

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

`$(` `".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` `);`

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

`$(` `".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 );`

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

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

Get or set the hide option, after initialization:

`// getter` `var` `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:

`$(` `".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 );`

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

`$(` `".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 );`

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

`$(` `".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 );`

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

`$(` `".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 );`

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

`$(` `".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` `);`

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

`$(` `".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 } );`

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

`$(` `".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` `);`

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

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

Get or set the show option, after initialization:

`// getter` `var` `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:

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

Get or set the stack option, after initialization:

`// getter` `var` `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:

`$(` `".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"` `);`

### widthType: Number

Default: `300`
The width of the dialog, in pixels.
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 );`

### zIndexType: Integer

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

Initialize the dialog with the zIndex option specified:

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

Get or set the zIndex option, after initialization:

`// getter` `var` `zIndex = $(` `".selector"` `).dialog(` `"option"``,` `"zIndex"` `);` `// setter` `$(` `".selector"` `).dialog(` `"option"``,` `"zIndex"``, 20 );`

## Methods

### close()

Closes the dialog.

- This method does not accept any arguments.

Code examples:

Invoke the close method:

`$(` `".selector"` `).dialog(` `"close"` `);`

### destroy()

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:

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

### disable()

Disables the dialog.

- This method does not accept any arguments.

Code examples:

Invoke the disable method:

`$(` `".selector"` `).dialog(` `"disable"` `);`

### enable()

Enables the dialog.

- This method does not accept any arguments.

Code examples:

Invoke the enable method:

`$(` `".selector"` `).dialog(` `"enable"` `);`

### isOpen() Returns: Boolean

Whether the dialog is currently open.

- This method does not accept any arguments.

Code examples:

Invoke the isOpen method:

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

### moveToTop()

Moves the dialog to the top of the dialog stack.

- This method does not accept any arguments.

Code examples:

Invoke the moveToTop method:

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

### open()

Opens the dialog.

- This method does not accept any arguments.

Code examples:

Invoke the open method:

`$(` `".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:

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

### option() Returns: PlainObject

Gets an object containing key/value pairs representing the current dialog options hash.

- This method does not accept any arguments.

Code examples:

Invoke the method:

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

### option( optionName, value )

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:

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

### option( options )

Sets one or more options for the dialog.

- options
  Type: Object
  A map of option-value pairs to set.

Code examples:

Invoke the method:

`$(` `".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:

`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

Code examples:

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`

Triggered when the dialog is closed.

- event
  Type: Event
- ui
  Type: Object

Code examples:

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`

Triggered when the dialog is created.

- event
  Type: Event
- ui
  Type: Object

Code examples:

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`

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:

`$(` `".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`

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:

`$(` `".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`

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:

`$(` `".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`

Triggered when the dialog gains focus.

- event
  Type: Event
- ui
  Type: Object

Code examples:

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`

Triggered when the dialog is opened.

- event
  Type: Event
- ui
  Type: Object

Code examples:

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`

Triggered while the dialog is being resized.

- event
  Type: Event
- ui
  Type: Object
  - orginalPosition
    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:

`$(` `".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`

Triggered when the user starts resizing the dialog.

- event
  Type: Event
- ui
  Type: Object
  - orginalPosition
    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:

`$(` `".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`

Triggered after the dialog has been resized.

- event
  Type: Event
- ui
  Type: Object
  - orginalPosition
    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:

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

Bind an event listener to the dialogresizestop event:

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

## Overview

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.

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

## 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``=``"http://code.jquery.com/ui/1.9.1/themes/base/jquery-ui.css"``>` `` `<``script` `src``=``"http://code.jquery.com/jquery-1.8.2.js"``></``script``>` `` `<``script` `src``=``"http://code.jquery.com/ui/1.9.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``>`

#### Demo: