4.33.0

Navigation (displayed along top of page)

Top-level navigation

This component is ready to be used by SuperCUP apps in production. Implementation details are available in the SuperCUP Navigation Migration Wiki.

Updated navigation documentation: <aui-sidenav>

Demo

const navItems = [ { "label": "Home", "dataRef": "aui-supernav.home", "url": "https://home.avalara.com" }, { "label": "Transactions", "dataRef": "aui-supernav.transactions.menu-trigger", "menuItems": [ { "label": "AvaTax", "menuItems": [ { "label": "View and edit", "url": "https://admin.avalara.com/transactions", "dataRef": "aui-supernav.avatax.transactionsNavMenuList" }, { "label": "Import", "url": "https://admin.avalara.com/transactions/batch-upload", "dataRef": "aui-supernav.avatax.transactionsNavMenuUpload" } ] }, { "label": "Consumer Use", "menuItems": [ { "label": "View and edit", "url": "https://acu.avalara.com/transactions", "dataRef": "aui-supernav.acu.transactionsNavMenuList" }, { "label": "Import", "url": "https://acu.avalara.com/transactions/batch-upload", "dataRef": "aui-supernav.acu.transactionsNavMenuUpload" } ] } ] }, { "label": "Exemptions", "url": "<>/customers", "dataRef": "aui-supernav.exemptionsMenuItem" }, { "label": "Returns", "dataRef": "aui-supernav.returns.menu-trigger", "menuItems": [ { "label": "Approve returns", "url": "https://returns.avalara.com/returns/worksheet", "dataRef": "aui-supernav.returnsMenuManage" }, { "label": "Filed returns and confirmations", "url": "https://returns.avalara.com/returns/history", "dataRef": "aui-supernav.returnsMenuFiled", "disabled": true, "descriptor": "This item is unavailable" }, { "label": "All scheduled returns", "url": "https://returns.avalara.com/returns/filing-calendars", "dataRef": "aui-supernav.returnsMenuScheduled" }, { "label": "Tax notices", "url": "https://qa.account.avalara.io/#/goto/tax-notices", "dataRef": "aui-supernav.returnsMenuTaxNotices", "disabled": true }, { "label": "Funding Power of Attorney", "url": "https://returns.avalara.com/returns/funding/history", "dataRef": "aui-supernav.returnsMenuPOA" } ] } ]; document.querySelector('aui-supernav').navItems = navItems; document.querySelector('aui-supernav').navHandler = (event, href) => { console.log(event, href); event.preventDefault(); };

API

Tag

Name Description
<aui-supernav> Custom Element, no content

Attributes

Name Value Required Description
active dataRef of a top-level navItem

Sets the active top-level nav item, e.g. `aui-supernav.transactions`.
companyid String

In the majority of cases, the company ID will be pulled from the aui-context cookie, but this attribute is available for overriding the cookie's value.
accountid String

In the majority of cases, the account ID will be pulled from the aui-context cookie, but this attribute is available for overriding the cookie's value.
i18n string

A stringified JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Properties

Name Value Required Description
active dataRef of a top-level navItem

Sets the active top-level nav item, e.g. `aui-supernav.transactions`.
companyId String

In the majority of cases, the company ID will be pulled from the aui-context cookie, but this attribute is available for overriding the cookie's value.
accountId String

In the majority of cases, the account ID will be pulled from the aui-context cookie, but this attribute is available for overriding the cookie's value.
requestCurrentAccessToken Function Function that returns a Promise resolving to {accessToken: "<avalara-ui-access-token>"}.

Events

Name Detail Description
s-navitemsloaded The navItems are available on e.detail

Fired when the navItems are successfully loaded. May be emitted multiple times if getNavigationJson() is called during the user session.

Methods

Name Description
getNavigationJson() Call this method to re-fetch JSON from the navigation service and update <aui-supernav>. Invoking this method is not necessary for the initial navigation fetch/render, only subsequent fetching/rendering for updates during a user session. See guidelines.

Demo

API

Tag

Name
<AuiSupernav>

Props

Name Value Required Description
requestCurrentAccessToken Function Function that returns a Promise resolving to {accessToken: "<avalara-ui-access-token>"}.
navHandler NavHandler function

Function to handle in-app navigation, see Guidelines below.
active dataRef of a top-level navItem

Sets the active top-level nav item, e.g. `aui-supernav.transactions`.
companyId String

In the majority of cases, the company ID will be pulled from the aui-context cookie, but this attribute is available for overriding the cookie's value.
accountId String

In the majority of cases, the account ID will be pulled from the aui-context cookie, but this attribute is available for overriding the cookie's value.
navItems Nav Items object

SuperCUP apps should never use this property. Instead, they will apply the requestCurrentAccessToken property, which will fetch items from the Web Platform Navigation Service. Other apps should apply a stringified array of nav items, see Guidelines below.
onSNavItemsLoaded Function

Handles the s-navitemsloaded event fired when the navItems are successfully loaded. This event may be emitted multiple times if getNavigationJson() is called during the user session.
i18n object

A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Methods

Name Description
getNavigationJson() Call this method to re-fetch JSON from the navigation service and update <AuiSupernav>. Invoking this method is not necessary for the initial navigation fetch/render, only subsequent fetching/rendering for navigation updates during a user session. See React-specific guidelines below for more information (as well as main guidelines).

React implementation notes

Using refs to call AuiSupernav method

In order to call the getNavigationJson() method, you must create a ref, assign it to the AuiSupernav component, and then use ref.current to access the method:

    
    const auiSupernavRef = React.createRef(); 
    
    function getNavigationJson() {
      auiSupernavRef.current.getNavigationJson();
    }
    
    return (
      <AuiSupernav ref={auiSupernavRef} />
    )

Skylab React links

General information about using our React package

i18n Strings

ID Description Default value
"supernav.ariaLabel.nav" The aria-label for the nav element main navigation

Guidelines

Providing the access token

Your app must set (via the requestCurrentAccessToken property) a function that returns a Promise resolving to {accessToken: "<avalara-ui-access-token>"}. The access token must have at least 5 seconds of life remaining.

Avalara Identity access tokens are short-lived by default, so it is essential that the requestCurrentAccessToken function either fetch an access token fresh from the server or have knowledge of a particular access token's expiration so it does not deliver a stale access token.

A sample implementation is shown in the Pioneer Demo app

There are two ways to populate the <aui-supernav> component with nav items:

  1. requestCurrentAccessToken

    SuperCUP apps must provide the requestCurrentAccessToken function to the component. When this function is set, the component will make a request to the Web Platform Navigation Service to fetch the navigation JSON for the customer and render it.

  2. navitems (attribute)/navItems (property)

    Non-SuperCUP apps must provide a formatted array of navItems to the <aui-supernav> component:

    See API below:

    // each navItem and menuItem must contain either "url" string, "menuItems" array, or true "disabled" boolean // if URL must be masked in disabled item, we recommend including "url" value of "#" // menuItems can extend to 2 levels deep, with product names assigned to "label" // "descriptor" is used in conjunction with "disabled: true" to display a short explanation for the disabled state of the menu item interface NavItem { label: string dataRef: string menuItems?: NavItem[] url?: string disabled?: boolean descriptor?: string }

    or data can be assigned as attribute using stringified array

Single page apps can optionally provide a navHandler function to manage routing within a single-page application (SPA). On any click of an <a> tag in <aui-supernav>, the navHandler will be invoked with two arguments: the mouse click event and the value of the href attribute in the associated <a> tag.

The typical implementation will include a conditional to determine if the URL is within the consumer's SPA and invocation of that SPA's router function (e.g. history.push in react-router) if so.

Sample usage is shown below for CUP (admin.avalara.com):

function handleNavigation(nativeMouseEvent, url) { if (url.includes("admin.avalara.com")) { nativeMouseEvent.preventDefault(); mySpaRouterFunction(url); } // nothing need be invoked for the case of a url not in the SPA // the default action will execute and the user will be routed to the new app and the page will be refreshed } document.querySelector('aui-supernav').navHandler = handleNavigation;

getNavigationJson function

If an event occurs during a user session that impacts the navigation content (e.g. TSA user switches to a different account), invoke the declarative getNavigationJson() method to refresh the navigation data.

Design

Design resources can be found on the Skylab design documentation site: skylab.avalara.com