Class Ui

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 to the editor.

 // 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.
 var ui = SpreadsheetApp.getUi();
 var 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

PropertyTypeDescription
ButtonButtonAn enum representing predetermined, localized dialog buttons returned by an alert or PromptResponse.getSelectedButton() to indicate which button in a dialog the user clicked.
ButtonSetButtonSetAn enum representing predetermined, localized sets of one or more dialog buttons that can be added to an alert or a prompt.

Methods

MethodReturn typeBrief description
alert(prompt)ButtonOpens a dialog box in the user's editor with the given message and an "OK" button.
alert(prompt, buttons)ButtonOpens a dialog box in the user's editor with the given message and set of buttons.
alert(title, prompt, buttons)ButtonOpens a dialog box in the user's editor with the given title, message, and set of buttons.
createAddonMenu()MenuCreates a builder that can be used to insert a sub-menu into the editor's Add-on menu.
createMenu(caption)MenuCreates a builder that can be used to add a menu to the editor's user interface.
prompt(prompt)PromptResponseOpens an input dialog box in the user's editor with the given message and an "OK" button.
prompt(prompt, buttons)PromptResponseOpens an input dialog box in the user's editor with the given message and set of buttons.
prompt(title, prompt, buttons)PromptResponseOpens an input dialog box in the user's editor with the given title, message, and set of buttons.
showModalDialog(userInterface, title)voidOpens a modal dialog box in the user's editor with custom client-side content.
showModelessDialog(userInterface, title)voidOpens a modeless dialog box in the user's editor with custom client-side content.
showSidebar(userInterface)voidOpens a sidebar 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 will resume after the user dismisses the dialog, but Jdbc connections and LockService locks will not persist across the suspension. For more information, see the guide to dialogs and sidebars.

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

NameTypeDescription
promptStringthe message to display in the dialog box

Return

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 will resume after the user dismisses the dialog, but Jdbc connections and LockService locks will not persist across the suspension. For more information, see the guide to dialogs and sidebars.

 // 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.
 var ui = SpreadsheetApp.getUi();
 var 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

NameTypeDescription
promptStringthe message to display in the dialog box
buttonsButtonSetthe button set to display in the dialog box

Return

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 will resume after the user dismisses the dialog, but Jdbc connections and LockService locks will not persist across the suspension. For more information, see the guide to dialogs and sidebars.

 // 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.
 var ui = SpreadsheetApp.getUi();
 var 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

NameTypeDescription
titleStringthe title to display above the dialog box
promptStringthe message to display in the dialog box
buttonsButtonSetthe button set to display in the dialog box

Return

Button — the button the user clicked


createAddonMenu()

Creates a builder that can be used to insert a sub-menu into the editor's Add-on menu. The menu will not actually be updated until Menu.addToUi() is called. If the script is running as an add-on, the sub-menu name will match the add-on's name in the web store; if the script is bound to the document directly, the sub-menu name will match the script's name. For more information, see the guide to menus.

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

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 will not actually be added until Menu.addToUi() is called. For more information, see the guide to 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, the caption parameter is ignored and the menu is added as a sub-menu of the Add-ons menu, equivalent to createAddonMenu().

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

NameTypeDescription
captionStringthe 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

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 will resume after the user dismisses the dialog, but Jdbc connections and LockService locks will not persist across the suspension. For more information, see the guide to dialogs and sidebars.

 // 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.
 var ui = SpreadsheetApp.getUi();
 var 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

NameTypeDescription
promptStringthe message to display in the dialog box

Return

PromptResponse — 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 will resume after the user dismisses the dialog, but Jdbc connections and LockService locks will not persist across the suspension. For more information, see the guide to dialogs and sidebars.

 // 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.
 var ui = SpreadsheetApp.getUi();
 var 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

NameTypeDescription
promptStringthe message to display in the dialog box
buttonsButtonSetthe button set to display in the dialog box

Return

PromptResponse — 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 will resume after the user dismisses the dialog, but Jdbc connections and LockService locks will not persist across the suspension. For more information, see the guide to dialogs and sidebars.

 // 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.
 var ui = SpreadsheetApp.getUi();
 var 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

NameTypeDescription
titleStringthe title to display above the dialog box
promptStringthe message to display in the dialog box
buttonsButtonSetthe button set to display in the dialog box

Return

PromptResponse — 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 either the google.script API for HtmlService or server handlers for UiApp. To close the dialog programmatically, call google.script.host.close() on the client side of an HtmlService web app or UiInstance.close() from a UiApp web app. For more information, see the guide to dialogs and sidebars.

Modal dialogs prevent the user from interacting with anything other than the dialog. By contrast, modeless dialogs and sidebars let the user interact with the editor. In almost all cases, a modal dialog or sidebar is a better choice than a modeless dialog.


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

 // Display a modal dialog box with custom UiApp content.
 var uiInstance = UiApp.createApplication()
     .setWidth(250)
     .setHeight(300);
 uiInstance.add(uiInstance.createLabel('The photograph on the dashboard taken years ago...'));
 SpreadsheetApp.getUi().showModalDialog(uiInstance, 'My add-on');
 

Parameters

NameTypeDescription
userInterfaceObjectan HtmlOutput or UiInstance web app
titleStringthe title of the dialog; overrides any title set by calling setTitle() on the userInterface object

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 either the google.script API for HtmlService or server handlers for UiApp. To close the dialog programmatically, call google.script.host.close() on the client side of an HtmlService web app or UiInstance.close() from a UiApp web app. For more information, see the guide to dialogs and sidebars.

Modeless dialogs let the user interact with the editor behind the dialog. By contrast, modal dialogs do not. In almost all cases, a modal dialog or sidebar is a better choice than a modeless dialog.


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

 // Display a modeless dialog box with custom UiApp content.
 var uiInstance = UiApp.createApplication()
     .setWidth(250)
     .setHeight(300);
 uiInstance.add(uiInstance.createLabel('The photograph on the dashboard taken years ago...'));
 SpreadsheetApp.getUi().showModelessDialog(uiInstance, 'My add-on');
 

Parameters

NameTypeDescription
userInterfaceObjectan HtmlOutput or UiInstance web app
titleStringthe title of the dialog; overrides any title set by calling setTitle() on the userInterface object

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 either the google.script API for HtmlService or server handlers for UiApp. To close the sidebar programmatically, call google.script.host.close() on the client side of an HtmlService web app or UiInstance.close() from a UiApp web app. For more information, see the guide to dialogs and sidebars.

The sidebar will display 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.


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

 // Display a sidebar with custom UiApp content.
 var uiInstance = UiApp.createApplication()
     .setTitle('My add-on');
 uiInstance.add(uiInstance.createLabel('The photograph on the dashboard taken years ago...'));
 SpreadsheetApp.getUi().showSidebar(uiInstance);
 

Parameters

NameTypeDescription
userInterfaceObjectan HtmlOutput or UiInstance web app

Deprecated methods

Send feedback about...

Apps Script
Apps Script