Ui

An instance of the user-interface environment for a Google App that allows the script to add
features like menus, dialogs, and sidebars. A script can only interact with the UI for the
current instance of an open editor, and only if the script is [container-bound](https://developers.google.com/apps-script/scripts_containers) to the editor.

```javascript
// Display a dialog box with a title, message, input field, and "Yes" and "No"
// buttons. The user can also close the dialog by clicking the close button in
// its title bar.
const ui = SpreadsheetApp.getUi();
const response = ui.prompt(
    'Getting to know you',
    'May I know your name?',
    ui.ButtonSet.YES_NO,
);

// Process the user's response.
if (response.getSelectedButton() === ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() === ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}
```

### Properties

| Property | Type | Description |
|---|---|---|
| `Button` | `https://developers.google.com/apps-script/reference/base/button` | An enum representing predetermined, localized dialog buttons returned by an [alert](https://developers.google.com/apps-script/reference/base/ui#alert(String)) or `https://developers.google.com/apps-script/reference/base/prompt-response#getSelectedButton()` to indicate which button in a dialog the user clicked. |
| `ButtonSet` | `https://developers.google.com/apps-script/reference/base/button-set` | An enum representing predetermined, localized sets of one or more dialog buttons that can be added to an [alert](https://developers.google.com/apps-script/reference/base/ui#alert(String,ButtonSet)) or a [prompt](https://developers.google.com/apps-script/reference/base/ui#prompt(String,ButtonSet)). |

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/base/ui#alert(String)` | `https://developers.google.com/apps-script/reference/base/button` | Opens a dialog box in the user's editor with the given message and an "OK" button. |
| `https://developers.google.com/apps-script/reference/base/ui#alert(String,ButtonSet)` | `https://developers.google.com/apps-script/reference/base/button` | Opens a dialog box in the user's editor with the given message and set of buttons. |
| `https://developers.google.com/apps-script/reference/base/ui#alert(String,String,ButtonSet)` | `https://developers.google.com/apps-script/reference/base/button` | Opens a dialog box in the user's editor with the given title, message, and set of buttons. |
| `https://developers.google.com/apps-script/reference/base/ui#createAddonMenu()` | `https://developers.google.com/apps-script/reference/base/menu` | Creates a builder that can be used to insert a sub-menu into the editor's Extensions menu. |
| `https://developers.google.com/apps-script/reference/base/ui#createMenu(String)` | `https://developers.google.com/apps-script/reference/base/menu` | Creates a builder that can be used to add a menu to the editor's user interface. |
| `https://developers.google.com/apps-script/reference/base/ui#prompt(String)` | `https://developers.google.com/apps-script/reference/base/prompt-response` | Opens an input dialog box in the user's editor with the given message and an "OK" button. |
| `https://developers.google.com/apps-script/reference/base/ui#prompt(String,ButtonSet)` | `https://developers.google.com/apps-script/reference/base/prompt-response` | Opens an input dialog box in the user's editor with the given message and set of buttons. |
| `https://developers.google.com/apps-script/reference/base/ui#prompt(String,String,ButtonSet)` | `https://developers.google.com/apps-script/reference/base/prompt-response` | Opens an input dialog box in the user's editor with the given title, message, and set of buttons. |
| `https://developers.google.com/apps-script/reference/base/ui#showModalDialog(Object,String)` | `void` | Opens a modal dialog box in the user's editor with custom client-side content. |
| `https://developers.google.com/apps-script/reference/base/ui#showModelessDialog(Object,String)` | `void` | Opens a modeless dialog box in the user's editor with custom client-side content. |
| `https://developers.google.com/apps-script/reference/base/ui#showSidebar(Object)` | `void` | Opens a sidebar in the user's editor with custom client-side content. |

### Deprecated methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/base/ui#showDialog(Object)` | `void` | Opens a dialog box in the user's editor with custom client-side content. |

## Detailed documentation

### `alert(prompt)`

Opens a dialog box in the user's editor with the given message and an "OK" button. This method
suspends the server-side script while the dialog is open. The script resumes after the user
dismisses the dialog, but `https://developers.google.com/apps-script/reference/jdbc/jdbc.html`
connections and `https://developers.google.com/apps-script/reference/lock/lock-service.html` locks don't
persist across the suspension. For more information, see the [guide to dialogs and sidebars](https://developers.google.com/apps-script/guides/dialogs).

```javascript
// Display "Hello, world" in a dialog box with an "OK" button. The user can also
// close the dialog by clicking the close button in its title bar.
SpreadsheetApp.getUi().alert('Hello, world');
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `prompt` | `String` | The message to display in the dialog box. |

#### Return


`https://developers.google.com/apps-script/reference/base/button` --- The button the user clicked.

*** ** * ** ***

### `alert(prompt, buttons)`

Opens a dialog box in the user's editor with the given message and set of buttons. This method
suspends the server-side script while the dialog is open. The script resumes after the user
dismisses the dialog, but `https://developers.google.com/apps-script/reference/jdbc/jdbc.html`
connections and `https://developers.google.com/apps-script/reference/lock/lock-service.html` locks don't
persist across the suspension. For more information, see the [guide to dialogs and sidebars](https://developers.google.com/apps-script/guides/dialogs).

```javascript
// Display a dialog box with a message and "Yes" and "No" buttons. The user can
// also close the dialog by clicking the close button in its title bar.
const ui = SpreadsheetApp.getUi();
const response = ui.alert(
    'Are you sure you want to continue?',
    ui.ButtonSet.YES_NO,
);

// Process the user's response.
if (response === ui.Button.YES) {
  Logger.log('The user clicked "Yes."');
} else {
  Logger.log(
      'The user clicked "No" or the close button in the dialog\'s title bar.',
  );
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `prompt` | `String` | The message to display in the dialog box. |
| `buttons` | `https://developers.google.com/apps-script/reference/base/button-set` | The button set to display in the dialog box. |

#### Return


`https://developers.google.com/apps-script/reference/base/button` --- The button the user clicked.

*** ** * ** ***

### `alert(title, prompt, buttons)`

Opens a dialog box in the user's editor with the given title, message, and set of buttons. This
method suspends the server-side script while the dialog is open. The script resumes after the
user dismisses the dialog, but `https://developers.google.com/apps-script/reference/jdbc/jdbc.html`
connections and `https://developers.google.com/apps-script/reference/lock/lock-service.html` locks don't
persist across the suspension. For more information, see the [guide to dialogs and sidebars](https://developers.google.com/apps-script/guides/dialogs).

```javascript
// Display a dialog box with a title, message, and "Yes" and "No" buttons. The
// user can also close the dialog by clicking the close button in its title bar.
const ui = SpreadsheetApp.getUi();
const response = ui.alert(
    'Confirm',
    'Are you sure you want to continue?',
    ui.ButtonSet.YES_NO,
);

// Process the user's response.
if (response === ui.Button.YES) {
  Logger.log('The user clicked "Yes."');
} else {
  Logger.log(
      'The user clicked "No" or the close button in the dialog\'s title bar.',
  );
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | The title to display above the dialog box. |
| `prompt` | `String` | The message to display in the dialog box. |
| `buttons` | `https://developers.google.com/apps-script/reference/base/button-set` | The button set to display in the dialog box. |

#### Return


`https://developers.google.com/apps-script/reference/base/button` --- The button the user clicked.

*** ** * ** ***

### `createAddonMenu()`

Creates a builder that can be used to insert a sub-menu into the editor's Extensions menu. The
menu isn't actually be updated until `https://developers.google.com/apps-script/reference/base/menu#addToUi()` is called. If the script is running
as an add-on, the sub-menu name matches the add-on's name in the web store; if the script is [bound](https://developers.google.com/apps-script/scripts_containers) to the document directly, the sub-menu name
matches the script's name. For more information, see the [guide to menus](https://developers.google.com/apps-script/guides/menus).

```javascript
// Add an item to the add-on menu, under a sub-menu whose name is set
// automatically.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createAddonMenu()
      .addItem('Show', 'showSidebar')
      .addToUi();
}
```

#### Return


`https://developers.google.com/apps-script/reference/base/menu` --- The new menu builder.

*** ** * ** ***

### `createMenu(caption)`

Creates a builder that can be used to add a menu to the editor's user interface. The menu isn't
actually be added until `https://developers.google.com/apps-script/reference/base/menu#addToUi()` is called. For more information, see the [guide to menus](https://developers.google.com/apps-script/guides/menus). The label for a top-level menu should be
in headline case (all major words capitalized), although the label for a sub-menu should be in
sentence case (only the first word capitalized). If the script is published as an [add-on](https://developers.google.com/gsuite/add-ons/overview), the `caption` parameter is ignored and the
menu is added as a sub-menu of the Extensions menu, equivalent to `https://developers.google.com/apps-script/reference/base/ui#createAddonMenu()`.

```javascript
// Add a custom menu to the active document, including a separator and a
// sub-menu.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createMenu('My Menu')
      .addItem('My menu item', 'myFunction')
      .addSeparator()
      .addSubMenu(
          SpreadsheetApp.getUi()
              .createMenu('My sub-menu')
              .addItem('One sub-menu item', 'mySecondFunction')
              .addItem('Another sub-menu item', 'myThirdFunction'),
          )
      .addToUi();
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `caption` | `String` | The label for the menu, with all major words capitalized for a top-level menu, or only the first word capitalized for a sub-menu. |

#### Return


`https://developers.google.com/apps-script/reference/base/menu` --- The new menu builder.

*** ** * ** ***

### `prompt(prompt)`

Opens an input dialog box in the user's editor with the given message and an "OK" button. This
method suspends the server-side script while the dialog is open. The script resumes after the
user dismisses the dialog, but `https://developers.google.com/apps-script/reference/jdbc/jdbc.html`
connections and `https://developers.google.com/apps-script/reference/lock/lock-service.html` locks don't
persist across the suspension. For more information, see the [guide to dialogs and sidebars](https://developers.google.com/apps-script/guides/dialogs).

```javascript
// Display a dialog box with a message, input field, and an "OK" button. The
// user can also close the dialog by clicking the close button in its title bar.
const ui = SpreadsheetApp.getUi();
const response = ui.prompt('Enter your name:');

// Process the user's response.
if (response.getSelectedButton() === ui.Button.OK) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `prompt` | `String` | The message to display in the dialog box. |

#### Return


`https://developers.google.com/apps-script/reference/base/prompt-response` --- A representation of the user's response.

*** ** * ** ***

### `prompt(prompt, buttons)`

Opens an input dialog box in the user's editor with the given message and set of buttons. This
method suspends the server-side script while the dialog is open. The script resumes after the
user dismisses the dialog, but `https://developers.google.com/apps-script/reference/jdbc/jdbc.html`
connections and `https://developers.google.com/apps-script/reference/lock/lock-service.html` locks don't
persist across the suspension. For more information, see the [guide to dialogs and sidebars](https://developers.google.com/apps-script/guides/dialogs).

```javascript
// Display a dialog box with a message, input field, and "Yes" and "No" buttons.
// The user can also close the dialog by clicking the close button in its title
// bar.
const ui = SpreadsheetApp.getUi();
const response = ui.prompt('May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() === ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() === ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `prompt` | `String` | The message to display in the dialog box. |
| `buttons` | `https://developers.google.com/apps-script/reference/base/button-set` | The button set to display in the dialog box. |

#### Return


`https://developers.google.com/apps-script/reference/base/prompt-response` --- A representation of the user's response.

*** ** * ** ***

### `prompt(title, prompt, buttons)`

Opens an input dialog box in the user's editor with the given title, message, and set of
buttons. This method suspends the server-side script while the dialog is open. The script
resumes after the user dismisses the dialog, but `https://developers.google.com/apps-script/reference/jdbc/jdbc.html` connections and `https://developers.google.com/apps-script/reference/lock/lock-service.html` locks don't persist across the
suspension. For more information, see the [guide to
dialogs and sidebars](https://developers.google.com/apps-script/guides/dialogs).

```javascript
// Display a dialog box with a title, message, input field, and "Yes" and "No"
// buttons. The user can also close the dialog by clicking the close button in
// its title bar.
const ui = SpreadsheetApp.getUi();
const response = ui.prompt(
    'Getting to know you',
    'May I know your name?',
    ui.ButtonSet.YES_NO,
);

// Process the user's response.
if (response.getSelectedButton() === ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() === ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | The title to display above the dialog box. |
| `prompt` | `String` | The message to display in the dialog box. |
| `buttons` | `https://developers.google.com/apps-script/reference/base/button-set` | The button set to display in the dialog box. |

#### Return


`https://developers.google.com/apps-script/reference/base/prompt-response` --- A representation of the user's response.

*** ** * ** ***

### `showModalDialog(userInterface, title)`

Opens a modal dialog box in the user's editor with custom client-side content. This method does
*not* suspend the server-side script while the dialog is open. To communicate with the
server-side script, the client-side component must make asynchronous callbacks using the [`google.script`](https://developers.google.com/apps-script/guides/html/communication) API for `https://developers.google.com/apps-script/reference/html/html-service.html`. To close the dialog
programmatically, call [`google.script.host.close()`](https://developers.google.com/apps-script/guides/html#serve_html_as_a_google_docs_sheets_or_forms_user_interface) on the client side of an `HtmlService` web
app. For more information, see the [guide to dialogs and
sidebars](https://developers.google.com/apps-script/guides/dialogs).

Modal dialogs prevent the user from interacting with anything other than the dialog. By
contrast, [modeless dialogs](https://developers.google.com/apps-script/reference/base/ui#showModelessDialog(Object,String)) and [sidebars](https://developers.google.com/apps-script/reference/base/ui#showSidebar(Object)) let the user interact with the editor. In almost all cases, a
modal dialog or sidebar is a better choice than a modeless dialog.

```javascript
// Display a modal dialog box with custom HtmlService content.
const htmlOutput = HtmlService
                       .createHtmlOutput(
                           '<p>A change of speed, a change of style...</p>',
                           )
                       .setWidth(250)
                       .setHeight(300);
SpreadsheetApp.getUi().showModalDialog(htmlOutput, 'My add-on');
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `userInterface` | `Object` | An `https://developers.google.com/apps-script/reference/html/html-output.html` representing the interface to display. |
| `title` | `String` | The title of the dialog; overrides any title set by calling `setTitle()` on the `userInterface` object. |

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/script.container.ui`

*** ** * ** ***

### `showModelessDialog(userInterface, title)`

Opens a modeless dialog box in the user's editor with custom client-side content. This method
does *not* suspend the server-side script while the dialog is open. To communicate with
the server-side script, the client-side component must make asynchronous callbacks using the [`google.script`](https://developers.google.com/apps-script/guides/html/communication) API for `https://developers.google.com/apps-script/reference/html/html-service.html`. To close the dialog
programmatically, call [`google.script.host.close()`](https://developers.google.com/apps-script/guides/html#serve_html_as_a_google_docs_sheets_or_forms_user_interface) on the client side of an `HtmlService` web
app. For more information, see the [guide to dialogs and
sidebars](https://developers.google.com/apps-script/guides/dialogs).

Modeless dialogs let the user interact with the editor behind the dialog. By contrast,
[modal dialogs](https://developers.google.com/apps-script/reference/base/ui#showModalDialog(Object,String)) do not. In almost all cases, a modal
dialog or [sidebar](https://developers.google.com/apps-script/reference/base/ui#showSidebar(Object)) is a better choice than a modeless dialog.

```javascript
// Display a modeless dialog box with custom HtmlService content.
const htmlOutput = HtmlService
                       .createHtmlOutput(
                           '<p>A change of speed, a change of style...</p>',
                           )
                       .setWidth(250)
                       .setHeight(300);
SpreadsheetApp.getUi().showModelessDialog(htmlOutput, 'My add-on');
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `userInterface` | `Object` | An `https://developers.google.com/apps-script/reference/html/html-output.html` representing the interface to display. |
| `title` | `String` | The title of the dialog; overrides any title set by calling `setTitle()` on the `userInterface` object. |

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/script.container.ui`

*** ** * ** ***

### `showSidebar(userInterface)`

Opens a sidebar in the user's editor with custom client-side content. This method does
*not* suspend the server-side script while the sidebar is open. To communicate with the
server-side script, the client-side component must make asynchronous callbacks using the [`google.script`](https://developers.google.com/apps-script/guides/html/communication) API for `https://developers.google.com/apps-script/reference/html/html-service.html`. To close the sidebar
programmatically, call [`google.script.host.close()`](https://developers.google.com/apps-script/guides/html#serve_html_as_a_google_docs_sheets_or_forms_user_interface) on the client side of an `HtmlService` web
app. For more information, see the [guide to dialogs and
sidebars](https://developers.google.com/apps-script/guides/dialogs).

The sidebar displays on the right side of the editor for users whose environments use a
left-to-right language and on the left side of the editor for right-to-left languages. All
sidebars shown by scripts are 300 pixels wide.

```javascript
// Display a sidebar with custom HtmlService content.
const htmlOutput = HtmlService
                       .createHtmlOutput(
                           '<p>A change of speed, a change of style...</p>',
                           )
                       .setTitle('My add-on');
SpreadsheetApp.getUi().showSidebar(htmlOutput);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `userInterface` | `Object` | An `https://developers.google.com/apps-script/reference/html/html-output.html` representing the interface to display. |

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/script.container.ui`

## Deprecated methods

### `showDialog(userInterface)`


**Deprecated.** As of March 2014, this method is deprecated. The direct replacement is `https://developers.google.com/apps-script/reference/base/ui#showModelessDialog(Object,String)`, but `https://developers.google.com/apps-script/reference/base/ui#showModalDialog(Object,String)` is a
better choice in almost all cases.

Opens a dialog box in the user's editor with custom client-side content. This method does
*not* suspend the server-side script while the dialog is open. To communicate with the
server-side script, the client-side component must make asynchronous callbacks using the [`google.script`](https://developers.google.com/apps-script/guides/html/communication) API for `https://developers.google.com/apps-script/reference/html/html-service.html`. To close the dialog
programmatically, call [`google.script.host.close()`](https://developers.google.com/apps-script/guides/html#serve_html_as_a_google_docs_sheets_or_forms_user_interface) on the client side of an `HtmlService` web
app. For more information, see the [guide to dialogs and
sidebars](https://developers.google.com/apps-script/guides/dialogs).

```javascript
// Display a dialog box with custom HtmlService content.
const htmlOutput = HtmlService
                       .createHtmlOutput(
                           '<p>A change of speed, a change of style...</p>',
                           )
                       .setTitle('My add-on')
                       .setWidth(250)
                       .setHeight(300);
SpreadsheetApp.getUi().showDialog(htmlOutput);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `userInterface` | `Object` | An `https://developers.google.com/apps-script/reference/html/html-output.html` representing the interface to display. |

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/script.container.ui`