> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Side Nav – Design
> Side Navs are used to display a list of links to move between pages.
export const LiveCode = ({children, customHeight, clickToLoad, example, fullWidth, fullHeight, hideCodeInLiveCode, screenshot, screenshotOnly, showCode: showCodeProp}) => {
const SCREENSHOTS_BASE = "https://servicetitan.github.io/anvil2-docs-live-code/screenshots";
const STACKBLITZ_BASE = "https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples";
const [showCodeBlock, setShowCodeBlock] = useState(showCodeProp ?? false);
const [isLocalOverride, setIsLocalOverride] = useState(false);
useEffect(() => {
const examplePath = `/images/live-code-screenshots-tmp/${example}.png`;
fetch(examplePath, {
method: "HEAD"
}).then(r => {
if (r.ok) setIsLocalOverride(true);
}).catch(() => {});
}, [example]);
const screenshotBase = isLocalOverride ? "/images/live-code-screenshots-tmp" : SCREENSHOTS_BASE;
if (screenshotOnly) {
return
## Anatomy
The Side Nav consists of five primary elements that work together to display a list of links to move between pages.
1. Item
2. Selected item
3. Group section
4. Collapsible parent item
5. Nested item
## Options
The Side Nav supports flat list, grouping, and collapsible configurations to accommodate various navigation scenarios.
### Flat List
```tsx lines theme={null}
import { SideNav, type SideNavLinkProps } from "@servicetitan/anvil2";
import { useState, type MouseEvent } from "react";
function App() {
const [active, setActive] = useState("2");
const handleOnClick = (
_e: MouseEvent,
id: SideNavLinkProps["id"],
) => {
setActive(id);
};
return (
Side Nav Item 1
Side Nav Item 2
Side Nav Item 3
Side Nav Item 4
Side Nav Item 5
Side Nav Item 6
);
}
export default App;
```
### Grouping
```tsx lines theme={null}
import { SideNav, type SideNavLinkProps } from "@servicetitan/anvil2";
import { useState, type MouseEvent } from "react";
function App() {
const [active, setActive] = useState("2");
const handleOnClick = (
_e: MouseEvent,
id: SideNavLinkProps["id"],
) => {
setActive(id);
};
return (
Side Nav Item 1
Side Nav Item 2
Side Nav Item 3
Side Nav Item 4
Side Nav Item 5
Side Nav Item 6
);
}
export default App;
```
### Collapsible
Parent items are purely accordions, and are not links themselves.
```tsx lines theme={null}
import { SideNav, type SideNavLinkProps } from "@servicetitan/anvil2";
import { useState, type MouseEvent } from "react";
function App() {
const [active, setActive] = useState("2");
const handleOnClick = (
_e: MouseEvent,
id: SideNavLinkProps["id"],
) => {
setActive(id);
};
return (
Child Item 1
Child Item 2
Child Item 3
Child Item 1
Child Item 2
Child Item 3
Child Item 1
Child Item 2
Child Item 3
);
}
export default App;
```
## Behavior
The Side Nav responds to user interaction with distinct visual states and text overflow handling.
### Visual States
```tsx lines theme={null}
import { SideNav } from "@servicetitan/anvil2";
function App() {
return (
Rest
Hover
Active
Focus Visible
Disabled
);
}
export default App;
```
```tsx lines theme={null}
import { SideNav } from "@servicetitan/anvil2";
function App() {
return (
Selected Rest
Selected Hover
Selected Active
Selected Focus Visible
Selected Disabled
);
}
export default App;
```
### Text Overflow
Each item in the Side Nav will wrap when not enough space is available.
```tsx lines theme={null}
import { SideNav, type SideNavLinkProps } from "@servicetitan/anvil2";
import { useState, type MouseEvent } from "react";
function App() {
const [active, setActive] = useState("2");
const handleOnClick = (
_e: MouseEvent,
id: SideNavLinkProps["id"],
) => {
setActive(id);
};
return (
Child Item 1
Child item that will wrap when not enough space is available
Child Item 3
);
}
export default App;
```
## Usage Guidelines
Use the Side Nav to display a list of links for moving between pages.
### When to Use
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.
#### Use a collapsible Side Nav when users understand the hierarchy
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.
#### Use a flat Side Nav 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.
### Alternatives
#### Side Nav vs Tab
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. Side Navs are also able to organize less related items together compared to Tabs.
### How to Use
#### Pair 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.
```tsx lines theme={null}
import { SideNav, type SideNavLinkProps } from "@servicetitan/anvil2";
import { useState, type MouseEvent } from "react";
function App() {
const [active, setActive] = useState("2");
const handleOnClick = (
_e: MouseEvent,
id: SideNavLinkProps["id"],
) => {
setActive(id);
};
return (
Apple
Bananna
Orange
);
}
export default App;
```
#### Parent nav items can only be collapsible actions
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.
```tsx lines theme={null}
import { SideNav, type SideNavLinkProps } from "@servicetitan/anvil2";
import { useState, type MouseEvent } from "react";
function App() {
const [active, setActive] = useState("1");
const handleOnClick = (
_e: MouseEvent,
id: SideNavLinkProps["id"],
) => {
setActive(id);
};
return (
Overview
Button
Link
);
}
export default App;
```
#### Don't use 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.
```tsx lines theme={null}
import { SideNav, type SideNavLinkProps } from "@servicetitan/anvil2";
import { useState, type MouseEvent } from "react";
function App() {
const [active, setActive] = useState("2");
const handleOnClick = (
_e: MouseEvent,
id: SideNavLinkProps["id"],
) => {
setActive(id);
};
return (
Child Item 1
Grandchild Item 1
Grandchild Item 2
Child Item 1
Child Item 2
Child Item 3
);
}
export default App;
```
**Don't**
#### Don't add 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.
```tsx lines theme={null}
import { SideNav, Button, type SideNavLinkProps } from "@servicetitan/anvil2";
import Edit from "@servicetitan/anvil2/assets/icons/material/round/edit.svg";
import { useState, type MouseEvent } from "react";
function App() {
const [active, setActive] = useState("2");
const handleOnClick = (
_e: MouseEvent,
id: SideNavLinkProps["id"],
) => {
setActive(id);
};
return (
Side Nav Item 1
Side Nav Item 2
Side Nav Item 3
Side Nav Item 4
Side Nav Item 5
Side Nav Item 6
);
}
export default App;
```
**Don't**
#### Showing metadata with Chips
A [Chip](/docs/web/components/chip/design) can be paired with the Side Nav. It can be used to provide metadata such as beta or new status, or a numerical value related to the Side Nav item.
```tsx lines theme={null}
import {
SideNav,
Flex,
Chip,
type SideNavLinkProps,
} from "@servicetitan/anvil2";
import { core } from "@servicetitan/anvil2/token";
import { useState, type MouseEvent } from "react";
function App() {
const [active, setActive] = useState("2");
const handleOnClick = (
_e: MouseEvent,
id: SideNavLinkProps["id"],
) => {
setActive(id);
};
return (
Side Nav Item
Side Nav Item
Side Nav Item
Side Nav Item
Side Nav Item
);
}
export default App;
```
## 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. |
