A script is bound to a Google Sheets, Docs, Slides, or Forms file if it was created from that document rather than as a standalone script. The file that a bound script is attached to is called a "container." Bound scripts generally behave like standalone scripts except that they do not appear in Google Drive, they cannot be detached from the file they are bound to, and they gain a few special privileges over the parent file.
Note that scripts can also be bound to Google Sites, but these scripts are almost always deployed as web apps. Scripts bound to Google Sheets, Docs, Slides, or Forms can also become web apps, although this is uncommon.
Create a bound script
Google Docs, Sheets, or Slides
To create a bound script in Google Docs, Sheets, or Slides, open a document in Docs, a spreadsheet in Sheets, or a presentation in Slides and click Extensions > Apps Script. To reopen the script in the future, do the same thing or open the script from the Apps Script dashboard.
Google Forms
To create a bound script in Google Forms, open a form and click More > Script editor. To reopen the script in the future, do the same thing or open the script from the Apps Script dashboard.
Special methods
Bound scripts can call a few methods that standalone scripts cannot:
getActiveSpreadsheet()
,getActiveDocument()
,getActivePresentation()
, andgetActiveForm()
allow bound scripts to refer to their parent file without referring to the file's ID.getUi
lets bound scripts access the user interface for their parent file to add custom menus, dialogs, and sidebars.- In Google Sheets,
getActiveSheet()
,getActiveRange()
, andgetActiveCell()
let the script determine the user's current sheet, selected range of cells, or selected individual cell.setActiveSheet(sheet)
andsetActiveRange(range)
let the script change those selections. - In Google Docs,
getActiveTab()
,getCursor()
, andgetSelection()
let the script determine the user's current tab, position of the user's cursor, or selected text.setActiveTab(tabId)
,setCursor(position)
andsetSelection(range)
let the script change those selections.
For more information, see the guide to extending Google Sheets or the guide to extending Google Docs.
Custom menus, dialogs, and sidebars
Bound scripts can customize Google Sheets, Docs, and Forms by adding custom menus and dialog boxes or sidebars. Keep in mind, however, that a script can only interact with the user interface for the current instance of an open file. That is, a script bound to one document cannot affect the user interface of another document.
Add-ons
Add-ons run inside Gmail, Google Sheets, Docs, Slides, and Forms. If you've developed a bound or standalone script and want to share it with the world, Apps Script lets you publish your script as an add-on so other users can install it from the add-on store.
Triggers
Bound scripts can use simple triggers
like the special onOpen()
function, which runs automatically whenever a file
is opened by a user who has edit access. Like all types of scripts, they can
also use installable triggers.
Custom functions
A custom function is a function in a
script bound to Google Sheets that you call directly from a cell using the
syntax =myFunctionName()
. Custom functions are thus similar to the hundreds of
built-in functions in Sheets
like AVERAGE
or
SUM
except that you define
the custom function's behavior.
Access to bound scripts
Only users who have permission to edit a container can run its bound script. Collaborators who have only view access can't open the script editor, although if they make a copy of the container file, they become the owner of the copy and can see and run a copy of the script.
To learn how to share a script's container file, refer to Share files from Google Drive.