Navigation (displayed along side of page)

Top-level navigation

Legacy component documentation: <aui-supernav>

Demo

No live demo is available for the side nav because some elements will not show up correctly in the context of this page. Please note the parent div in the code sample which wraps the side nav and main content; your app's HTML must be structured this way, and the parent div must be given class="flex align-items-stretch" for the side nav and other content to display properly.

Handling Company Changes

When users change their active company through the company switcher, your application must listen for the s-change-company event and reload any company-specific data. This is critical because the company switcher no longer causes a page refresh.

Basic Event Handling

// Listen for company changes (event bubbles up from aui-sidenav) document.addEventListener('s-change-company', (event) => { const { company, initialLoad } = event.detail; console.log('Company changed to:', company.name, `(${company.companyCode})`); console.log('Company ID:', company.id); console.log('Is initial load:', initialLoad); // Reload company-specific data if (!initialLoad) { // User actively changed the company - reload your data reloadCompanyData(company.id); } else { // Initial load - set up your app with the active company initializeWithCompany(company.id); } });

API

Tag

Name	Description
`<aui-sidenav>`	Custom Element, no content

Attributes

Name	Value	Description
`active`	`dataRef` of a top-level navItem	Sets the active top-level nav item.
`companyid`	String	By default, the company ID is automatically determined from the `skylab_current_company_<env>` cookie, or the default company if no cookie exists. This attribute allows you to override this automatic selection. See Company Persistence & Cookies for details.
`accountid`	String	By default, the account ID is automatically determined from the `aui-context` cookie. This attribute allows you to override this automatic selection.
`navitems`	String	SuperCUP apps should never use this attribute. 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.
`hidecompanyswitcher`	Boolean	When present, the company switcher will be hidden.
`hidecontact`	Boolean	When present, the contact information will be hidden.
`cam`	String	Stringified JSON of cam object, see Guidelines below.
`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	Description
`active`	`dataRef` of a top-level navItem	Sets the active top-level nav item.
`companyId`	String	By default, the company ID is automatically determined from the `skylab_current_company_<env>` cookie, or the default company if no cookie exists. This property allows you to override this automatic selection. See Company Persistence & Cookies for details.
`accountId`	String	By default, the account ID is automatically determined from the `aui-context` cookie. This property allows you to override this automatic selection.
`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.
`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.
`hideCompanySwitcher`	Boolean	When present, the company switcher will be hidden.
`hideContact`	Boolean	When present, the contact information will be hidden.
`cam`	JSON	Set this to cam object JSON, see Guidelines below.
`i18n`	object	A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Events

Name Detail Description

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.
`s-change-company`	The `SCompanyChangeEvent` object is available on `e.detail`	Fired when the company switcher sub-component changes the company. ⚠️ Important: Teams must listen for this event and reload any company-specific data. Previously, the company switcher was a separate page that users would navigate to, so navigating back to your page would refresh the data. Now that the company switcher is embedded in the sidenav, there's no page refresh when the company changes, so your application must handle data reloading manually. The event is fired with `initialLoad: true` when the component first loads and determines the active company, and `initialLoad: false` when the user actively changes the company.

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.

s-change-company

The SCompanyChangeEvent object is available on e.detail

Fired when the company switcher sub-component changes the company.

⚠️ Important: Teams must listen for this event and reload any company-specific data. Previously, the company switcher was a separate page that users would navigate to, so navigating back to your page would refresh the data. Now that the company switcher is embedded in the sidenav, there's no page refresh when the company changes, so your application must handle data reloading manually.

The event is fired with initialLoad: true when the component first loads and determines the active company, and initialLoad: false when the user actively changes the company.

Methods

Name	Description
`getNavigationJson()`	Call this method to re-fetch JSON from the navigation service and update `<aui-sidenav>`. 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

Handling Company Changes

When users change their active company through the company switcher, your React application must listen for the s-change-company event and reload any company-specific data. This is critical because the company switcher no longer causes a page refresh.

Basic Event Handling

// Listen for company changes in React component useEffect(() => { const handleCompanyChange = (event) => { const { company, initialLoad } = event.detail; console.log('Company changed to:', company.name, `(${company.companyCode})`); console.log('Company ID:', company.id); console.log('Is initial load:', initialLoad); // Reload company-specific data if (!initialLoad) { // User actively changed the company - reload your data reloadCompanyData(company.id); } else { // Initial load - set up your app with the active company initializeWithCompany(company.id); } }; document.addEventListener('s-change-company', handleCompanyChange); }, []);

API

Tag

Name
`<AuiSidenav>`

Props

Name	Value	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.
`companyId`	String	By default, the company ID is automatically determined from the `skylab_current_company_<env>` cookie, or the default company if no cookie exists. This property allows you to override this automatic selection. See Company Persistence & Cookies for details.
`accountId`	String	By default, the account ID is automatically determined from the `aui-context` cookie. This property allows you to override this automatic selection.
`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.
`hideCompanySwitcher`	Boolean	When present, the company switcher will be hidden.
`hideContact`	Boolean	When present, the contact information will be hidden.
`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.
`cam`	JSON	Set this to cam object JSON. See Guidelines.
`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 AuiSidenav method

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

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

Skylab React links

General information about using our React package

Company Persistence & Cookies

The sidenav component automatically persists the user's selected company using browser cookies. Understanding this system is important for teams implementing company-specific functionality.

Cookie Name

When a user selects a company through the company switcher, the component stores the company ID in an environment-specific cookie: skylab_current_company_<env>

Environment Normalization

The cookie name includes a normalized environment suffix to ensure proper isolation between environments:

dev → skylab_current_company_dev
local, ci, qa → skylab_current_company_qa
sbx → skylab_current_company_sbx
All other environments (e.g., prd, prod) → skylab_current_company_prd

Company Selection Logic

On initial load, the component determines which company to display using this priority:

Cookie: If skylab_current_company_<env> cookie exists, use that company ID
Default: If no cookie exists, select the default company from the user's company list

Automatic Behavior

The sidenav component handles cookie management automatically:

On initial load: Reads cookie to restore the user's previously selected company
On company change: Updates cookie when user switches companies via the company switcher
On companyId prop change: Updates cookie when the prop is set programmatically

Important Notes

Host applications do NOT need to manage this cookie. The skylab components handle all cookie reading and writing automatically.
The cookie is domain-wide and secure, allowing consistent company selection across all applications in the same environment.
For applications using the companyId prop, the cookie will still be updated to maintain consistency across page refreshes.
Note: The legacy aui-context cookie is used only for accountId, not for company selection.

Typescript

Exported types

// CAM object provided to component export type CamObject = Record; // User object provided to component export type UserObject = Record; // NavItem object provided (in an array) to component export type NavItem = { label: string; dataRef: string; menuItems?: NavItem[]; url?: string; icon?: string; disabled?: boolean; descriptor?: string; i18nKey?: string; }; // s-navitemsloaded event's e.detail export type SNavItemsLoadedEvent = { navItems: NavItem[]; }; // company object for s-change-company event export type CompanyItem = { id?: number; companyCode: string; name: string; parentCompanyId?: number; isDefault?: boolean; isActive?: boolean; parentCompanyName?: string; }; // s-change-company event's e.detail export type SCompanyChangeEvent = { company: CompanyItem; initialLoad: boolean; };

i18n Strings

ID	Description	Default value
`"sidenav.ariaLabel.nav"`	The aria-label for the nav element	main navigation
`"sidenav.ariaLabel.toggleExpand"`	The aria-label used for the button that horizontally expands the side nav.	Expand menu
`"sidenav.ariaLabel.toggleCollapse"`	The aria-label used for the button that horizontally collapses the side nav.	Collapse menu

Guidelines

Page layout requirements

In order to display properly, the side nav and main content containers must be wrapped in a parent div which is styled with display: flex and align-items: stretch. See the code sample at the top of this page for an example. In addition, the aui-header accompanying the side nav must be given the sidenavheader attribute in order to be styled correctly.

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

requestCurrentAccessToken and navitems

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

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.
navitems (attribute)/navItems (property)
Non-SuperCUP apps must provide a formatted array of navItems to the <aui-sidenav> 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 icon?: string // required for top-level NavItem menuItems?: NavItem[] url?: string disabled?: boolean descriptor?: string }
or data can be assigned as attribute using stringified array

Customer Account Manager object

The customer's Salesforce account information is retrieved via the OPUS API (see Swagger). That customerAccount object contains a key named camOwned that indicates if the account's cam key contains valid Customer Account Manager data. The value of camOwned should be assigned to the isValid key and passed along with the cam object to the <aui-sidenav> as follows:

const customerAccount = await getCustomerAccountFromOpus(customerId); const modifiedCamObject = customerAccount.cam ? { ...customerAccount.cam, isValid: customerAccount.camOwned } : null; document.querySelector('aui-sidenav').cam = modifiedCamObject;

or data can be assigned as attribute using stringified JSON

If the cam object includes a photoUrl field, the linked image will be displayed in the contact dialog. If no photoUrl is defined or the image fails to load, a default user icon will be displayed instead.

Valid active attribute values

In contrast to the top nav, which permits only a small set of values for the active attribute, any nav item's dataRef can be provided to the side nav as an active value.

Nav handler

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-sidenav>, 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-sidenav').navHandler = handleNavigation;

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.

Setting Active Company with companyId Prop

Use the companyId prop to programmatically set the active company (e.g., from URL parameters, deep links, or application logic).

// Set the companyId prop const sidenav = document.querySelector('aui-sidenav'); sidenav.companyId = '12345'; // Listen for the s-change-company event sidenav.addEventListener('s-change-company', (event) => { const { company, initialLoad } = event.detail; if (!initialLoad) { console.log('Company changed to:', company.name); } });

Note: The prop accepts a company ID as a string. Listen for the s-change-company event to know when the change completes. Validation errors are logged to the console.

Automatic State Persistence

The sidenav automatically remembers the user's expansion preference. When users toggle between expanded and collapsed states, their choice is saved and restored on subsequent visits to maintain a consistent experience.

Technical details: Preferences are saved to environment-specific browser cookies and are restored automatically. This ensures users maintain their preferred navigation width across all applications within the same environment.

Design

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

Demo

Handling Company Changes

Basic Event Handling

API

Tag

Attributes

Properties

Events

Methods

Demo

Handling Company Changes

Basic Event Handling

API

Tag

Props

Methods

React implementation notes

Using refs to call AuiSidenav method

Skylab React links

Company Persistence & Cookies

Cookie Name

Environment Normalization

Company Selection Logic

Automatic Behavior

Important Notes

Typescript

Exported types

i18n Strings

Guidelines

Page layout requirements

Providing the access token

requestCurrentAccessToken and navitems

Customer Account Manager object

Valid active attribute values

Nav handler

getNavigationJson function

Setting Active Company with companyId Prop

Automatic State Persistence

Design