Side Nav - Web

For development, import SideNav from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Side Nav consists of five primary elements that work together to display a list of links to move between pages.

Item
Selected item
Group section
Collapsible parent item
Nested item

Options

The Side Nav supports flat list, grouping, and collapsible configurations to accommodate various navigation scenarios.

Flat List

Grouping

Collapsible

Parent items are purely accordions, and are not links themselves.

Behavior

The Side Nav responds to user interaction with distinct visual states and text overflow handling.

Visual States

Text Overflow

Each item in the Side Nav will wrap when not enough space is available.

Usage Guidelines

Standard	Requirement
DoDisplay links for moving between pages	Use the Side Nav to display a list of links for moving between pages.
DoMatch the app’s navigation structure	Use the Side Nav based on how the larger app organizes its navigation structure. In some cases this means the Side Nav is the top-level navigation tool, in others it may be a secondary system.
DoUse collapsible when hierarchy is clear	Use a collapsible Side Nav when users understand the categorization, helping them find items more effectively. Avoid this structure if there’s no clear parent-child relation in the nav, especially if users cannot perceive it.
DoUse flat for fewer or semi-related items	Use a flat Side Nav when items in a group lack a clear hierarchy. A flattened Side Nav is easier for users to navigate in this situation.
DoPair subheaders and collapsible in complex navs	Navigations with nuanced levels of hierarchy can use both subheaders and nesting at once. Simpler navigations should consider using only one grouping method.
DoShow metadata with Chips	A Chip can be paired with the Side Nav to provide metadata such as beta or new status, or a numerical value related to the Side Nav item.
Don’tMake a parent item a link	The Side Nav’s parent item can never be a link. If a parent item link is needed, a child item at the top may be used in its place, e.g., Overview.
Don’tUse multi-nested Navs	The Side Nav does not support deep navigation. Simplify the navigation structure first. If it cannot be simplified, a custom solution is needed.
Don’tAdd secondary actions	The Side Nav does not support secondary actions for accessibility reasons. Consider placing these actions elsewhere, such as on the page the Side Nav item goes to.

Alternatives

Side Nav vs Tabs

Side Navs and Tabs perform similar tasks of organizing content. In most situations, Side Navs are a higher level of the navigation structure compared to Tabs, and are also able to organize less related items together compared to Tabs.

Content

Content within the Side Nav should clearly communicate navigation destinations through descriptive labels.

Keyboard Interaction

Users can navigate the Side Nav using standard keyboard controls.

Key	Interaction
Down Arrow	Moves focus to next item
Up Arrow	Moves focus to previous item
Enter or Space	Selects item, expands/collapses. Focus stays on that item.

Code

Implementation
SideNav Props
SideNav.Link Props
SideNav.Group Props
SideNav.Collapsible Props

Common Examples

import { SideNav } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <SideNav>
      <SideNav.Item id="item-1">Item 1</SideNav.Item>
      <SideNav.Item id="item-2">Item 2</SideNav.Item>
    </SideNav>
  );
}

Grouping side nav items

Side nav items can be grouped in two different ways, using SideNav.Group or SideNav.Collapsible.

Using SideNav.Group

Use the SideNav.Group component to group multiple links.

Using SideNav.Collapsible

To make groups of items collapsible, use the SideNav.Collapsible component.

Routing with Side Nav Links

As of version 1.16.9, the pathname prop of the SideNav.Link component enables native browser routing using the history.pushState() function. This is essentially what react-router-dom does, and this method prevents extra dependencies in the @servicetitan/anvil2 package.

<SideNav.Link pathname="/example/path">Example Path</SideNav.Link>

React Accessibility

When there is more than one navigation landmark on a page, each should have a unique label. For example, if a SideNav exists on the same page as another navigational element, such as an app bar using a nav element, they should both have unique labels.Reference: W3 Navigation LandmarkFor more guidance on semantic page structure and navigation landmarks, see semantic markup best practices.

import { SideNav } from "@servicetitan/anvil2";

function ExampleComponent() {
return <SideNav aria-label="Main navigation">...</SideNav>;
}

`SideNav` Props

The SideNav component can accept any valid HTML nav element props.

import { SideNav } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <SideNav.Link
      id="link-1"
      pathname="/example"
      active={false}
      exact={false}
    >
      Link Text
    </SideNav.Link>
  );
}

`SideNav.Link` Props

The SideNav.Link component can accept any valid HTML a props, as well as the following:

string

required

Unique identifier for the navigation link. Required to enable keyboard navigation.

boolean

When true, marks the link as the current active page.

boolean

When true, disables the link and prevents interaction.

string

Pathname for client-side routing. Using this will trigger History API navigation.

string

Optional search parameters for the URL. Can only be used if pathname has a value.

import { SideNav } from "@servicetitan/anvil2";

function ExampleComponent() {
return (

<SideNav.Group label="Group Label">
  <SideNav.Link id="link-1">Link 1</SideNav.Link>
</SideNav.Group>
); }

`SideNav.Group` Props

The SideNav.Group component can accept any valid HTML li props, as well as the following:

string

required

The label text displayed for the navigation group.

import { SideNav } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <SideNav.Collapsible label="Collapsible Group" defaultExpanded={false}>
      <SideNav.Link id="link-1">Link 1</SideNav.Link>
    </SideNav.Collapsible>
  );
}

`SideNav.Collapsible` Props

The SideNav.Collapsible component can accept any valid HTML li props, as well as the following:

string

required

The label text displayed for the collapsible section.

boolean

default:"false"

Initial expansion state for uncontrolled usage.

boolean

Controlled expansion state.

Concepts & Guidelines

Anvil2

Resources

Side Nav - Web

Anatomy

Options

Flat List

Grouping

Collapsible

Behavior

Visual States

Text Overflow

Usage Guidelines

Alternatives

Side Nav vs Tabs

Content

Keyboard Interaction

Code

Common Examples

Grouping side nav items

Using SideNav.Group

Using SideNav.Collapsible

Routing with Side Nav Links

React Accessibility

Multiple Navigation Landmark

`SideNav` Props

`SideNav.Link` Props

`SideNav.Group` Props

`SideNav.Collapsible` Props

​Anatomy

​Options

​Flat List

​Grouping

​Collapsible

​Behavior

​Visual States

​Text Overflow

​Usage Guidelines

​Alternatives

​Side Nav vs Tabs

​Content

​Keyboard Interaction

​Code

​Common Examples

​Grouping side nav items

​Using SideNav.Group

​Using SideNav.Collapsible

​Routing with Side Nav Links

​React Accessibility

​Multiple Navigation Landmark

​SideNav Props

​SideNav.Link Props

​SideNav.Group Props

​SideNav.Collapsible Props

Anatomy

Options

Flat List

Grouping

Collapsible

Behavior

Visual States

Text Overflow

Usage Guidelines

Alternatives

Side Nav vs Tabs

Content

Keyboard Interaction

Code

Common Examples

Grouping side nav items

Using SideNav.Group

Using SideNav.Collapsible

Routing with Side Nav Links

React Accessibility

Multiple Navigation Landmark

`SideNav` Props

`SideNav.Link` Props

`SideNav.Group` Props

`SideNav.Collapsible` Props