Class google.script.run (Client-side API)
google.script.run is an asynchronous client-side JavaScript API available inHTML-service pages that can call server-side Apps Script functions. To interact with dialogs or sidebars in Google Docs, Sheets, or Forms from client-side code, usegoogle.script.host. For more information, see theguide to communicating with server functions in HTML service.
Methods
| Method | Return type | Brief description |
|---|---|---|
myFunction(...) (any server-side function) | void | Executes the server-side Apps Script function with the corresponding name. |
withFailureHandler(function) | google.script.run | Sets a callback function to run if the server-side function throws an exception. |
withSuccessHandler(function) | google.script.run | Sets a callback function to run if the server-side function returns successfully. |
withUserObject(object) | google.script.run | Sets an object to pass as a second parameter to the success and failure handlers. |
Detailed documentation
myFunction(...) (any server-side function)
Executes the server-side Apps Script function with the corresponding name.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index');}function doSomething() { Logger.log('I was called!');}Index.html
<!DOCTYPE html><html> <head> <base> <script> google.script.run.doSomething(); </script> </head> <body> </body></html>
Parameters
| Name | Type | Description |
|---|---|---|
... | Most types are legal, but notDate,Function, or DOM element besidesform; see description | Legal parameters are JavaScript primitives like aNumber,Boolean,String, ornull, as well as JavaScript objects and arrays that are composed of primitives, objects, and arrays. Aform element within the page is also legal as a parameter, but it must be the function’s only parameter. Requests fail if you attempt to pass aDate,Function, DOM element besides aform, or other prohibited type, including prohibited types inside objects or arrays. Objects that create circular references will also fail, and undefined fields within arrays becomenull. Note that an object passed to the server becomes a copy of the original. If a server function receives an object and changes its properties, the properties on the client are not affected. |
Return
void — this method is asynchronous and does not return directly; however, the server-side function can return a value to the client as a parameter passed to asuccess handler; also, return types are subject to the same restrictions as parameter types, except that aform element is not a legal return type
withFailureHandler(function)
Sets a callback function to run if the server-side function throws an exception. TheError object is passed to the function as the first argument, and theuser object (if any) is passed as a second argument. Without a failure handler, failures are logged to the JavaScript console. To override this, callwithFailureHandler(null) or supply a failure handler that does nothing.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index');}function getUnreadEmails() { // 'got' instead of 'get' will throw an error. return GmailApp.gotInboxUnreadCount();}Index.html
<!DOCTYPE html><html> <head> <base> <script> function onFailure(error) { var div = document.getElementById('output'); div.innerHTML = "ERROR: " + error.message; } google.script.run.withFailureHandler(onFailure) .getUnreadEmails(); </script> </head> <body> <div></div> </body></html>Parameters
| Name | Type | Description |
|---|---|---|
function | Function | a client-side callback function to run if the server-side function throws an exception; theError object is passed to the function as the first argument, and theuser object (if any) is passed as a second argument |
Return
google.script.run — this "script runner," for chaining
withSuccessHandler(function)
Sets a callback function to run if the server-side function returns successfully. The server's return value is passed to the function as the first argument, and theuser object (if any) is passed as a second argument.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index');}function getUnreadEmails() { return GmailApp.getInboxUnreadCount();}Index.html
<!DOCTYPE html><html> <head> <base> <script> function onSuccess(numUnread) { var div = document.getElementById('output'); div.innerHTML = 'You have ' + numUnread + ' unread messages in your Gmail inbox.'; } google.script.run.withSuccessHandler(onSuccess) .getUnreadEmails(); </script> </head> <body> <div></div> </body></html>Parameters
| Name | Type | Description |
|---|---|---|
function | Function | a client-side callback function to run if the server-side function returns successfully; the server's return value is passed to the function as the first argument, and theuser object (if any) is passed as a second argument |
Return
google.script.run — this "script runner," for chaining
withUserObject(object)
Sets an object to pass as a second parameter to the success and failure handlers. This "user object" — not to be confused with theUser class — lets the callback functions respond to the context in which the client contacted the server. Because user objects are not sent to the server, they are not subject to the restrictions on parameters and return values forserver calls. User objects cannot, however, be objects constructed with thenew operator.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index');}function getEmail() { return Session.getActiveUser().getEmail();}Index.html
<!DOCTYPE html><html> <head> <base> <script> function updateButton(email, button) { button.value = 'Clicked by ' + email; } </script> </head> <body> <input type="button" value="Not Clicked" /> </body></html>Parameters
| Name | Type | Description |
|---|---|---|
object | Object | an object to pass as a second parameter to the success and failure handlers; because user objects are not sent to the server, they are not subject to the restrictions on parameters and return values forserver calls. User objects cannot, however, be objects constructed with thenew operator |
Return
google.script.run — this "script runner," for chaining
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-06-06 UTC.