Skip to main content

NavMenu

This namespace contains functionality associated with adding navigation items to the navigation menu of Gmail. Typically, these navigation links are accessible by the user on the left side of the email client and include built in navigation items like the Inbox, Sent Mail or Drafts links.

This namespace allows you to add your own items to this Navigation menu. Typically, these navigation items are useful to send users to different Routes that you have already registered providing navigation for your entire application. The navigation menu is represented as a tree structure of items. Each item can have 0 or more children and there are several options to configure the appearance of the items. Items can also have accessories which provide secondary actions like opening a dropdown (like Gmails labels) or providing a "create new" action. There are several predefined accesories, see CreateAccessoryDescriptor, IconButtonAccessoryDescriptor or DropdownButtonAccessoryDescriptor.

Namespace methods#

addNavItem(navItemDescriptor)#

Adds a navigation item to the root of the navigation menu. Navigation items from your app are grouped together where possible but ultimately the SDK optimizes for the best user experience when displaying navigation items.

ParametersTypeDescription
navItemDescriptorNavItemDescriptorA single descriptor for the nav item or stream of NavItemDescriptors.

Returns a NavItemView


NavItemView#

NavItemsViews are the elements placed inside a NavMenu. Each NavItemView represents an entry in the left navigation of Gmail. These NavItemViews can be nested.

Typically the main action of a NavItemView is performed when the user clicks on the main text. However, you can also provide accessories which are secondary actions which typically appear on the right side of the NavItemView but may be rendered in other ways. For nested NavItemViews, the SDK will handle collapsing and expanding children depending on user input.

Methods#

addNavItem(navItemDescriptor)#

Add a nested child NavItemView

ParametersTypeDescription
navItemDescriptorNavItemDescriptorA single descriptor for the nav item or stream of NavItemDescriptors.

Returns a NavItemView

remove()#

Remove this NavItemView from its parent

isCollapsed()#

Returns a boolean whether the NavItemView is currently collapsed and hiding its children

setCollapsed(collapseValue)#

Collapse or uncollapse this NavItemView

ParametersTypeDescription
collapseValuebooleanwhether to collapse or uncollapse

Events#

destroy#

Fires when this view is destroyed.

Properties#

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

NavItemDescriptor#

This object represents the set of options to configure a new NavItemView.

PropertyTypeDescriptionRequired?Default
namestringName of the NavItem to be used for displayYes
keystringUnique identifier for the nav item used for remembering collapse state between sessions.Novalue of name
routeIDstringThe ID of the route to navigate to when the NavItemView is clicked on.Nonull
routeParamsObjectThe parameters of the route being navigated to when the NavItemView is clicked on.Nonull
onClickfunctionA function that will be called when the NavItemView is clicked. Passed a single event object parameter which includes a preventDefault() function. If the NavItemView has a routeID, calling preventDefault() will prevent navigation to the given route.Nonull
orderHintintegerUsed to specify the order in which your NavItemViews should be relative to each otherNoNumber.MAX_SAFE_INTEGER
accessoryCreateAccessoryDescriptor or IconButtonAccessoryDescriptor or DropdownButtonAccessoryDescriptorThere are several "accessories" which can provide secondary actions for NavItemViewsNonull
iconUrlstringAn optional url to an icon to display an icon alongside the name of the NavItemViewNonull
iconClassstringAn optional class to apply to the icon.Nonull
iconElementHTMLElementAn optional icon element to use as the icon. This property can't be used with iconUrl or iconClass.Nonull
backgroundColorstringIf you provide none of the iconUrl, iconElement, iconClass properties, then a colored circle will be displayed next to the NavItemView that has its color set by this property, or gray by default.Nonull
typeNavItemTypesThe nav item type affects how the item is displayed.NoNAVIGATION

CreateAccessoryDescriptor#

The CreateAccessoryDescriptor allows you to add an action to allow the user to create a new child of this item.

PropertyTypeDescriptionRequired?Default
typestringFor CreateAccessoryDescriptors this should always be set to CREATEYes
onClickfunctionCallback for when the "Create New" accessory is pressed.Yes

IconButtonAccessoryDescriptor#

The IconButtonAccessoryDescriptor allows you to add an icon button right next your NavItem which lets the user take a secondary action

PropertyTypeDescriptionRequired?Default
typestringFor IconButtonAccessoryDescriptors this should always be set to ICON_BUTTONYes
onClickfunctionCallback for when the IconButton accessory is pressed.Yes
iconUrlstringA URL for the icon to be displayed in the button.Yes
iconClassstringAn optional class to add to the icon.Nonull

DropdownButtonAccessoryDescriptor#

The DropdownButtonAccessoryDescriptor allows you to add a dropdown right next your NavItemView

PropertyTypeDescriptionRequired?Default
typestringFor DropdownButtonAccessoryDescriptors this should always be set to DROPDOWN_BUTTONYes
onClickfunction(event)A callback when the dropdown button is pressed. The event object passed to you has a dropdown property which you can fill your content with.Yes

Enums and Constants#

NavItemTypes#

EnumDescription
NAVIGATIONstandard nav item for navigating
LINKnav item that looks like a link