Toolbars

The Toolbar namespace allows you to add your own buttons and actions to various toolbars in Gmail or Inbox. Toolbars appear in various Lists, ThreadViews and MessageViews. Within a toolbar, you have control over the placement of your buttons.

Toolbar buttons are typically used to take actions on the email(s) that the toolbar applies to. Do not use this API to add buttons that don't take a direct action on the selected email. Since toolbar buttons only apply to emails, they will ONLY appear when an email is selected or you are on a ThreadView.

Naemspace methods#

registerThreadButton(toolbarButtonDescriptor)#

Registers a toolbar button to appear on thread rows, above the thread list when some rows are checked, and above threads.

ParametersTypeDescription
toolbarButtonDescriptorToolbarButtonDescriptorThe options for the button.

Returns a function which removes the button registration.

registerToolbarButtonForList(toolbarButtonDescriptor)#

(This function is deprecated in favor of registerThreadButton.) Registers a toolbar button to appear above any list page such as the Inbox or Sent Mail.

ParametersTypeDescription
toolbarButtonDescriptorLegacyToolbarButtonDescriptorThe options for the button.

Returns a function which removes the button registration.

registerToolbarButtonForThreadView(toolbarButtonDescriptor)#

(This function is deprecated in favor of registerThreadButton.) Registers a toolbar button to appear when viewing a thread.

ParametersTypeDescription
toolbarButtonDescriptorLegacyToolbarButtonDescriptorThe options for the button.

Returns a function which removes the button registration.

addToolbarButtonForApp(appToolbarButtonDescriptor)#

Adds a button and dropdown to the "Global Toolbar". This is typically used to show a dropdown with general information about your application. In Gmail this refers to the navigation area at the top right of the window and in Inbox it refers to the top level toolbar.

ParametersTypeDescription
appToolbarButtonDescriptorAppToolbarButtonDescriptorThe options for the app toolbar button

Returns a AppToolbarButtonView

ToolbarButtonDescriptor#

This type is passed into the Toolbars.registerThreadButton() to configure the toolbar button shown.

PropertyTypeDescriptionRequired?Default
titlestringText to show when the user hovers the mouse over the button, or to show on the button when the user has the Gmail "Button labels" setting set to "Text".Yes
iconUrlstringURL for the icon to show on the button. Should be a local extension file URL or a HTTPS URL. Either this property, iconClass, or both must be specified.Nonull
iconClassstringAn optional class to apply to the icon. Either this property, iconUrl, or both must be specified.Nonull
positionsArray<string>An optional array of strings specifying the locations the button will be displayed in. The default value of null is treated as equal to the array of all of the possible values: "THREAD", "ROW", and "LIST".Nonull
threadSectionSectionNamesThe section of the toolbar to place the button when placing it on a thread. Currently this option only has an effect in Gmail.No'METADATA_STATE'
listSectionSectionNamesThe section of the toolbar to place the button when placing it above a thread list. Currently this option only has an effect in Gmail.No'METADATA_STATE'
onClickfunction(event)This is called when the button is clicked, and gets passed an event object. The event object will have a position property set to 'THREAD', 'ROW', or 'LIST' specifying where the button was that was interacted with. The event object will have selectedThreadViews (ThreadView[]) and selectedThreadRowViews (ThreadRowView[]) properties containing the thread or thread row objects that this button was activated on. The event object will have a dropdown (DropdownView) property if the hasDropdown property was set to true on the button descriptor.Yes
hasDropdownbooleanIf true, the button will open a dropdown menu above it, and the event object will have a dropdown property of type DropdownView that allows the dropdown to be customized when opened.Nofalse
hideForfunction(RouteView)A function that determines when this toolbar button should be hidden. You may want to hide the toolbar button on certain Routes or in certain conditions. The function should return true when the toolbar button should be hidden. Your function is passed a RouteView.Nonull
orderHintnumberIf multiple buttons are placed next to each other, then they will be ordered by this value.No0
keyboardShortcutHandlekeyboardShortcutHandleThe keyboard shortcut that will activate this button. This is currently only supported in Gmail.Nonull

LegacyToolbarButtonDescriptor#

This type is passed into the Toolbars.registerToolbarButtonForList() and Toolbars.registerToolbarButtonForThreadView() method as a way to configure the toolbar button shown.

PropertyTypeDescriptionRequired?Default
titlestringText to show when the user hovers the mouse over the button, or to show on the button when the user has the Gmail "Button labels" setting set to "Text".Yes
iconUrlstringURL for the icon to show on the button. Should be a local extension file URL or a HTTPS URL. Either this property, iconClass, or both must be specified.Nonull
iconClassstringAn optional class to apply to the icon. Either this property, iconUrl, or both must be specified.Nonull
sectionSectionNamesThe section of the toolbar to place the button.Yes
onClickfunction(event)This is called when the button is clicked, and gets passed an event object. If this was registered with Toolbars.registerToolbarButtonForList(), then the event object will have a selectedThreadRowViews (ThreadRowView[]) property and a threadRowViews (ThreadRowView[]) property. If this was registered with Toolbars.registerToolbarButtonForThreadView(), then the event object will have a threadView (ThreadView) property. In both cases the event object will optionally have a dropdown (DropdownView) property if you set the hasDropdown property to true on the descriptorYes
hasDropdownbooleanIf true, the button will open a dropdown menu above it, and the event object will have a dropdown property of type DropdownView that allows the dropdown to be customized when opened.Nofalse
hideForfunction(RouteView)A function that determines when this toolbar button should be hidden. You may want to hide the toolbar button on certain Routes or in certain conditions. The function should return true when the toolbar button should be hidden. Your function is passed a RouteView.Nonull
keyboardShortcutHandlekeyboardShortcutHandleThe keyboard shortcut that will activate this button.Nonull

AppToolbarButtonDescriptor#

This type is passed into the Toolbars.addToolbarButtonForApp() method as a way to configure the toolbar button shown.

PropertyTypeDescriptionRequired?Default
titlestringText to show on the button.Yes
titleClassstringAn optional class to apply to the title.Nonull
iconUrlstringURL for the icon to show on the button. Should be a local extension file URL or a HTTPS URL.Yes
iconClassstringAn optional class to apply to the icon.Nonull
onClickfunction(event)This is called when the button is clicked, and gets passed an event object. The event object will have a dropdown (DropdownView) property.Yes
arrowColorstringThe color to use for the top arrow of the dropdown. Useful if you want the contents of your dropdown to have a specific background colorNonull

AppToolbarButtonView#

Object that represents an app toolbar button that has been already added to the top navigation area of Gmail or Inbox. This class is returned by Toolbars.addToolbarButtonForApp().

Methods#

open()#

Open the dropdown for the app toolbar button

close()#

Close the dropdown for the app toolbar button

remove()#

Remove the app toolbar button from Gmail/Inbox

Events#

destroy#

Fires when this view has been removed.

Properties#

PropertyTypeDescriptionRequired?Default
destroyedbooleanThis property is set to true once the view is destroyed.Yes

Enums and Constants#

SectionNames#

The different toolbar sections that exist

EnumDescription
INBOX_STATEThe section is for buttons that move emails out of or into the users inbox.
COLLAPSEDThis section is for buttons that alter metadata of emails. Common examples are labeling or moving an email.
METADATA_STATEThis sectiom is used for other actions. Typically these will be placed in the "More" menu in Gmail or in submenus in Inbox.