# Side navigation
A vertical list of links between the main areas of an app or documentation site, optionally in labeled groups. For a collapsible app sidebar, put it in a [Sidebar](/components/sidebar.md).
```tsx
// demo.tsx
import {SideNavigation} from '@earendil-works/elanor-react';
export default function SideNavigationDemo() {
return (
Workspace
Projects
MembersSettings
);
}
```
## Usage
```tsx
import {SideNavigation} from '@earendil-works/elanor-react';
;
```
Root renders a `nav`. `active` marks the current page with `aria-current="page"`: it gets the active fill and `semantic.color.text.primary` at `semantic.fontWeight.ui.selected`; other links are `semantic.color.text.secondary`. Groups are optional. Long labels wrap to two lines, then truncate.
## Sections
`Collapsible` holds a section that opens and closes, with a `CollapsibleTrigger` as its title and a `CollapsiblePanel` holding a `List` of links. It is built on Base UI's [Collapsible](https://base-ui.com/react/components/collapsible), like [Progressive disclosure](/components/progressive-disclosure.md). Pass `defaultOpen` to the section that contains the current page, or control it with `open` and `onOpenChange`; its title is marked like the current page. Nested links indent their text by `semantic.dimension.space.padding.xLarge`.
The panel grows and shrinks to its measured height with `semantic.transition.movement.disclosure`, the same in every browser, and changes instantly when the reader prefers reduced motion. Closed panels stay in the document (`keepMounted`), so their links are part of the page's HTML.
```tsx
// sections.tsx
import {SideNavigation} from '@earendil-works/elanor-react';
export default function SideNavigationSections() {
return (
IntroductionGuidesGetting started
Deploying a project
ReferenceCommand-line toolConfiguration file
);
}
```
## Icons
`iconStart` and `iconEnd` add decorative icons; the label names the link.
```tsx
// icons.tsx
import {FolderOpenIcon, GroupIcon, SettingsIcon} from '@earendil-works/elanor-icons-react';
import {SideNavigation} from '@earendil-works/elanor-react';
export default function SideNavigationIcons() {
return (
}>
Projects
}>
Members
}>
Settings
);
}
```
## Compact
`variant="compact"` shows only icons, with each label in a tooltip on hover and focus. Every link needs `iconStart`, `iconEnd`, or `compactContent`, such as initials; otherwise it throws. Labels and group labels stay available to screen readers.
Links with plain text are named from their text; give links with rich content an `aria-label`. Keep text-only documentation navigation expanded.
```tsx
// compact.tsx
import {FolderOpenIcon, GroupIcon, SettingsIcon} from '@earendil-works/elanor-icons-react';
import {SideNavigation} from '@earendil-works/elanor-react';
export default function SideNavigationCompact() {
return (
Workspace}>
Projects
}>
Members
}>
Settings
Alex Morgan
);
}
```
Compact navigation is one link wide: `semantic.dimension.size.medium` (32px). Switching `variant` keeps the same links, so focus and tab order are preserved. [Sidebar](/components/sidebar.md) switches it when the sidebar collapses.
## Static rendering
On pages rendered on the server without React in the browser, use the static root and sections; lists, items, and links stay the same. Bind the behaviors right after the navigation's markup, so restored sections and the scroll position are in place before the first paint:
```tsx
Guides…
```
```ts
import {createCollapsible, createSideNavigation, enhance} from '@earendil-works/elanor-react';
enhance({'side-navigation': createSideNavigation, collapsible: createCollapsible});
```
Sections open and close like [Collapsible](/components/collapsible.md)'s static parts. With `persist` on the root, the navigation keeps its scroll position and the states of sections with a `persist` name across pages, in session storage; a section with the current page stays open, and a section that find in page opens is remembered open. With a client-side router that replaces the navigation, call the behaviors' `destroy()` before the swap, so the scroll position is saved, and `enhance` again after it. Where the browser blocks session storage, as with cookies blocked, or it is full, the navigation reports the error and works without keeping its state. The current page's link scrolls into view when it is hidden.
## API
### `SideNavigation.Root`
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'default' \| 'compact'` | `'default'` | `compact` shows only each link's icon or `compactContent`, with the label in a tooltip. Every link then needs one of them. |
Renders `