---
title: "Side Nav"
description: "A vertical list of grouped links for the sections of a settings screen."
---

Use it for the sections of one area that a reader moves between without leaving it: server settings, user settings, an admin panel. For a hierarchy that opens and closes, use a [Tree](/docs/components/tree); for the steps of a task, a [Stepper](/docs/components/stepper).

An entry is a link when it has an `href` and a button when it does not, so the same component serves a routed app and one that swaps the content in place.

_Live example of Side Nav — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add side-nav
```

Files written — React: components/ui/side-nav.tsx. Vue: components/ui/side-nav/SideNav.vue, components/ui/side-nav/SideNavGroup.vue, components/ui/side-nav/SideNavItem.vue, components/ui/side-nav/index.ts.

## Usage

React:

```tsx
import { SideNav } from "@/components/ui/side-nav"
```

Vue:

```ts
import { SideNav, SideNavGroup, SideNavItem } from "@/components/ui/side-nav"
```

## API reference

**`SideNavGroup`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | The small heading over the group. Omit it for an unlabelled group. |

**`SideNavItem`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Makes the entry a link. Without it the entry is a button. |
| `current` | `boolean` | `false` | Marks the section being shown. |
| `variant` | `"default" \| "danger"` | `"default"` | `danger` is for an entry that destroys something. |
| `badge` | `number` | — | A count shown at the end of the entry. |
| `onClick / @click` | `(event) => void` | — | Called when the entry is activated. |

`SideNav` renders the `<nav>` and takes its attributes. On a `SideNavItem`, the class lands on the list item and every other attribute, such as `target`, `rel` or `disabled`, lands on the link or the button inside it. Put a destructive entry in a group of its own at the end, away from the links it could be mistaken for.

## Accessibility

It is a `<nav>` landmark and needs a name: pass `aria-label` to `SideNav`. Each group is a list labelled by its heading. The current entry carries `aria-current="page"`, which is also what paints it. Entries are ordinary links and buttons, reached with `Tab`. A badge is read as a bare number after the entry's text, so word the entry to make the count make sense ("Audit log 12").

## Tokens

Side Nav reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
