Page Summary

outlined_flag

• Google Sheets macros automate UI interactions and can be linked to keyboard shortcuts or accessed via the Extensions menu.

• Recording a macro automatically creates an Apps Script function in a bound project'smacros.gs file and updates the project manifest.

• Macros can be created or edited directly within the Apps Script editor, or existing Apps Script functions can be imported as macros.

• The manifest file structure defines the name, function, and optional keyboard shortcut for each macro.

• Macros are limited to bound scripts in Google Sheets and cannot be used in standalone scripts, web apps, add-ons, libraries, or other Google Workspace applications.

Google Sheets lets you recordmacros that duplicate aspecific series of UI interactions that you define. Once you've recorded amacro, you can link it to a keyboard shortcut in the formCtrl+Alt+Shift+Number. You can use that shortcut to quickly execute theexact macro steps again, typically in a different place or on different data.You can also activate the macro from the Google SheetsExtensions>Macros menu.

When you record a macro, Google Sheets automatically creates an Apps Scriptfunction (themacro function) that replicates the macro steps. The macrofunction is added to an Apps Script projectboundto the sheet, in a file titledmacros.gs. In the event that there isalready a project file bound to the sheet with that name, the macro functionis appended to it. Google Sheets also automatically updates the scriptprojectmanifest, recording the nameand keyboard shortcut assigned to the macro.

Since every recorded macro is defined entirely within Apps Script, you canedit them directly within the Apps Script editor. You can even write macrosfrom scratch in Apps Script, or take functions you've already written andturn them into macros.

Creating macros in Apps Script

You can take functions written in Apps Script and use them as macro functions.The easiest way to do this is byimporting an existing function from theGoogle Sheets editor.

Alternatively, you can create macros within the Apps Script editor byfollowing these steps:

1. In the Google Sheets UI, selectExtensions>Apps Script to open thescript bound to the sheet in the Apps Script editor.
2. Write the macro function. Macro functions should take no arguments and returnno values.
3. Edit yourscript manifestto create the macro and link it to the macro function. Assign it a uniquekeyboard shortcut and name.
4. Save the script project. The macro is then available for use in the sheet.
5. Test the macro function in the sheet to verify that functions as intended.

Editing macros

You can edit macros attached to a sheet by doing the following:

1. In the Google Sheets UI, selectExtensions>Macros>Manage macros.
2. Find the macro you want to edit and selectmore_vert > Edit macro. This opensthe Apps Script editor to the project file containing the macro function.
3. Edit the macro function to change the macro behavior.
4. Save the script project. The macro is then available for use in the sheet.
5. Test the macro function in the sheet to verify that functions as intended.

Importing functions as macros

If there is already a scriptbound to a sheet,you canimport a function in the script as a new macro and then assign ita keyboard shortcut. You can do this byediting the manifestfile and adding another element to thesheets.macros[] property.

Alternatively, follow these steps to import a function as a macro from theSheets UI:

1. In the Google Sheets UI, selectExtensions>Macros>Import.
2. Select a function from the list presented and then clickAdd function.
3. Selectclear to close the dialog.
4. SelectExtensions>Macros>Manage macros.
5. Locate the function you just imported in the list. Assign a unique keyboardshortcut to the macro. You can also change the macro name here; the namedefaults to the name of the function.
6. ClickUpdate to save the macro configuration.

Manifest structure for macros

The following manifest file example snippet shows the section of amanifest that defines Google Sheets macros.Thesheets section of the manifest defines the name and keyboard shortcutassigned to the macro and the name of the macro function.

  {    ...    "sheets": {      "macros": [{        "menuName": "QuickRowSum",        "functionName": "calculateRowSum",        "defaultShortcut": "Ctrl+Alt+Shift+1"      }, {        "menuName": "Headerfy",        "functionName": "updateToHeaderStyle",        "defaultShortcut": "Ctrl+Alt+Shift+2"      }]    }  }

See theSheets macro manifest resourcefor more details on how Sheets macro manifests are constructed.

Best practices

When creating or managing macros in Apps Script, it is recommended that youadhere to the following guidelines.

1. Macros are more performant when they are light-weight. Where possible, limitthe number of actions a macro takes.
2. Macros are best suited for rote operations that need to be repeatedfrequently with little or no configuration. For other operations, considerusing acustom menu item instead.
3. Always remember that macro keyboard shortcuts must be unique, and a givensheet can only have ten macros with shortcuts at any one time. Any additionalmacros can only be executed from theExtensions>Macros menu.
4. Macros that make changes to a single cell can be applied to a range ofcells by first selecting the full range and then activating the macro.This means it is often unnecessary to create macros that duplicate thesame operation across a predefined range of cells.

Things you can't do

There are a few restrictions on what you can do with macros:

Use macros outside bound scripts

Macros are defined in scripts bound to specific Google Sheets. Macrodefinitions are ignored if defined in astandalone script orweb app.

Define macros in Sheets add-ons

You cannot distribute macro definitions using aSheets add-on. Any macro definitions in a Sheetsadd-on project are ignored by users of that add-on.

Distribute macros in script libraries

You cannot distribute macro definitions using Apps Scriptlibraries.

Use macros outside of Google Sheets

Macros are only a feature in Google Sheets, and do not exist for Google Docs,Forms, or Slides.