jQuery UI dialog documentation

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

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

### appendToType: Selector

Default: `"body"`
Which element the dialog should be appended to. Regardless of the value set, the overlay for modal dialogs will always be appended to the body and cover the entire window. (version added: 1.10)
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"` `);`

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

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

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:

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

### titleType: String

Default: `null`
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 );`

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

### 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 ) {} );`

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