Side Nav
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; for the steps of a task, a 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.
newt-side-nav"use client"
import * as React from "react"
import {
SideNav,
SideNavGroup,
SideNavItem,
} from "@/registry/bases/newt/ui/side-nav"
const SECTIONS = ["Overview", "Roles", "Emoji"]
export default function SideNavDemo() {
const [section, setSection] = React.useState("Overview")
return (
<SideNav
aria-label="Server settings"
className="w-56 rounded-md bg-newt-bg-surface px-2"
>
<SideNavGroup label="Server">
{SECTIONS.map((name) => (
<SideNavItem
key={name}
current={section === name}
onClick={() => setSection(name)}
>
{name}
</SideNavItem>
))}
</SideNavGroup>
<SideNavGroup label="Moderation">
<SideNavItem
badge={12}
current={section === "Audit log"}
onClick={() => setSection("Audit log")}
>
Audit log
</SideNavItem>
</SideNavGroup>
<SideNavGroup>
<SideNavItem variant="danger">Delete server</SideNavItem>
</SideNavGroup>
</SideNav>
)
}<script setup lang="ts">
import { ref } from "vue"
import {
SideNav,
SideNavGroup,
SideNavItem,
} from "~~/registry/bases/newt/ui/side-nav"
const SECTIONS = ["Overview", "Roles", "Emoji"]
const section = ref("Overview")
</script>
<template>
<SideNav
aria-label="Server settings"
class="w-56 rounded-md bg-newt-bg-surface px-2"
>
<SideNavGroup label="Server">
<SideNavItem
v-for="name in SECTIONS"
:key="name"
:current="section === name"
@click="section = name"
>
{{ name }}
</SideNavItem>
</SideNavGroup>
<SideNavGroup label="Moderation">
<SideNavItem
:badge="12"
:current="section === 'Audit log'"
@click="section = 'Audit log'"
>
Audit log
</SideNavItem>
</SideNavGroup>
<SideNavGroup>
<SideNavItem variant="danger">Delete server</SideNavItem>
</SideNavGroup>
</SideNav>
</template>Installation
npx newtui@latest add side-navnpx shadcn@latest add @newtui/side-navnpx shadcn-vue@latest add @newtui/side-navpnpm dlx newtui@latest add side-navpnpm dlx shadcn@latest add @newtui/side-navpnpm dlx shadcn-vue@latest add @newtui/side-navyarn dlx newtui@latest add side-navyarn dlx shadcn@latest add @newtui/side-navyarn dlx shadcn-vue@latest add @newtui/side-navbunx newtui@latest add side-navbunx shadcn@latest add @newtui/side-navbunx shadcn-vue@latest add @newtui/side-navdeno run -A npm:newtui@latest add side-navdeno run -A npm:shadcn@latest add @newtui/side-navdeno run -A npm:shadcn-vue@latest add @newtui/side-navvlx newtui@latest add side-navvlx shadcn@latest add @newtui/side-navvlx shadcn-vue@latest add @newtui/side-navvp dlx newtui@latest add side-navvp dlx shadcn@latest add @newtui/side-navvp dlx shadcn-vue@latest add @newtui/side-navnubx newtui@latest add side-navnubx shadcn@latest add @newtui/side-navnubx shadcn-vue@latest add @newtui/side-navnlx newtui@latest add side-navnlx shadcn@latest add @newtui/side-navnlx shadcn-vue@latest add @newtui/side-navupx newtui@latest add side-navupx shadcn@latest add @newtui/side-navupx shadcn-vue@latest add @newtui/side-nav- newtui
- shadcn
- npm
- pnpm
- yarn
- bun
- deno
- vlt
- vp
- nub
- ni
- upm
The shadcn CLI needs the @newtui registry in your components.json. Set it up.
Copy the source into your project
import * as React from "react"
import { cn } from "@/lib/utils"
/*
* The vertical list of sections down the side of a settings screen: a named
* `<nav>` of groups. Pass `aria-label` to say what it navigates.
*/
const SideNav = React.forwardRef<HTMLElement, React.ComponentProps<"nav">>(
({ className, ...props }, ref) => (
<nav
ref={ref}
className={cn("flex w-full flex-col", className)}
{...props}
/>
)
)
SideNav.displayName = "SideNav"
export interface SideNavGroupProps extends React.ComponentProps<"div"> {
/** The small heading over the group. Omit it for an unlabelled group. */
label?: string
}
const SideNavGroup = React.forwardRef<HTMLDivElement, SideNavGroupProps>(
({ className, label, children, ...props }, ref) => {
const id = React.useId()
return (
<div
ref={ref}
className={cn(
"border-newt-border py-2 [&:not(:first-child)]:border-t",
className
)}
{...props}
>
{label === undefined ? null : (
<div
id={id}
className="px-2.5 py-1.5 text-xs font-bold uppercase tracking-[0.02em] text-newt-text-muted"
>
{label}
</div>
)}
<ul
aria-labelledby={label === undefined ? undefined : id}
className="m-0 flex list-none flex-col gap-0.5 p-0"
>
{children}
</ul>
</div>
)
}
)
SideNavGroup.displayName = "SideNavGroup"
export interface SideNavItemProps extends React.HTMLAttributes<HTMLElement> {
/** Makes the entry a link. Without it the entry is a button. */
href?: string
/** Marks the section being shown. */
current?: boolean
/** `danger` is for an entry that destroys something. */
variant?: "default" | "danger"
/** A count shown at the end of the entry. */
badge?: number
/** For a link: where it opens, and its relationship to the page. */
target?: string
rel?: string
/** For a button. */
disabled?: boolean
}
/*
* One entry. `className` lands on the list item; every other attribute and
* listener lands on the link or the button inside it, which is where a
* `target`, a `disabled` or an `onClick` belongs.
*/
const SideNavItem = React.forwardRef<HTMLLIElement, SideNavItemProps>(
(
{
className,
href,
current = false,
variant = "default",
badge,
target,
rel,
disabled,
children,
...props
},
ref
) => {
const itemClassName = cn(
"flex w-full cursor-pointer items-center justify-between gap-2 rounded-[var(--newt-radius-sm)] px-2.5 py-1.5 text-start font-[family-name:var(--newt-font-sans)] text-[15px] font-medium leading-5 no-underline transition-colors duration-fast ease-newt hover:bg-newt-bg-hover focus-visible:outline focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-newt-text-link disabled:cursor-not-allowed disabled:opacity-50 aria-[current=page]:bg-newt-bg-active",
variant === "danger"
? "text-newt-danger"
: "text-newt-text-secondary hover:text-newt-text-primary aria-[current=page]:text-newt-text-primary"
)
const content = (
<>
{children}
{badge === undefined ? null : (
<span className="min-w-4 rounded-full bg-newt-danger px-[5px] text-center text-[11px] font-bold leading-4 text-newt-on-accent">
{badge}
</span>
)}
</>
)
return (
<li ref={ref} className={className}>
{href === undefined ? (
<button
type="button"
disabled={disabled}
aria-current={current ? "page" : undefined}
className={itemClassName}
{...props}
>
{content}
</button>
) : (
<a
href={href}
target={target}
rel={rel}
aria-current={current ? "page" : undefined}
className={itemClassName}
{...props}
>
{content}
</a>
)}
</li>
)
}
)
SideNavItem.displayName = "SideNavItem"
export { SideNav, SideNavGroup, SideNavItem }<script setup lang="ts">
import type { HTMLAttributes } from "vue"
import { cn } from "@/lib/utils"
/*
* The vertical list of sections down the side of a settings screen: a named
* `<nav>` of groups. Pass `aria-label` to say what it navigates.
*/
const props = defineProps<{ class?: HTMLAttributes["class"] }>()
</script>
<template>
<nav :class="cn('flex w-full flex-col', props.class)"><slot /></nav>
</template><script setup lang="ts">
import { useId, type HTMLAttributes } from "vue"
import { cn } from "@/lib/utils"
const props = defineProps<{
class?: HTMLAttributes["class"]
/** The small heading over the group. Omit it for an unlabelled group. */
label?: string
}>()
const id = useId()
</script>
<template>
<div
:class="
cn('border-newt-border py-2 [&:not(:first-child)]:border-t', props.class)
"
>
<div
v-if="props.label !== undefined"
:id="id"
class="px-2.5 py-1.5 text-xs font-bold uppercase tracking-[0.02em] text-newt-text-muted"
>
{{ props.label }}
</div>
<ul
:aria-labelledby="props.label === undefined ? undefined : id"
class="m-0 flex list-none flex-col gap-0.5 p-0"
>
<slot />
</ul>
</div>
</template><script setup lang="ts">
import { computed, type HTMLAttributes } from "vue"
import { cn } from "@/lib/utils"
/*
* One entry. Attributes other than `class` land on the link or the button
* inside the list item, which is where a listener belongs.
*/
defineOptions({ inheritAttrs: false })
const props = withDefaults(
defineProps<{
class?: HTMLAttributes["class"]
/** Makes the entry a link. Without it the entry is a button. */
href?: string
/** Marks the section being shown. */
current?: boolean
/** `danger` is for an entry that destroys something. */
variant?: "default" | "danger"
/** A count shown at the end of the entry. */
badge?: number
}>(),
{ current: false, variant: "default" }
)
const itemClassName = computed(() =>
cn(
"flex w-full cursor-pointer items-center justify-between gap-2 rounded-[var(--newt-radius-sm)] px-2.5 py-1.5 text-start font-[family-name:var(--newt-font-sans)] text-[15px] font-medium leading-5 no-underline transition-colors duration-fast ease-newt hover:bg-newt-bg-hover focus-visible:outline focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-newt-text-link disabled:cursor-not-allowed disabled:opacity-50 aria-[current=page]:bg-newt-bg-active",
props.variant === "danger"
? "text-newt-danger"
: "text-newt-text-secondary hover:text-newt-text-primary aria-[current=page]:text-newt-text-primary"
)
)
</script>
<template>
<li :class="props.class">
<component
:is="props.href === undefined ? 'button' : 'a'"
v-bind="$attrs"
:type="props.href === undefined ? 'button' : undefined"
:href="props.href"
:aria-current="props.current ? 'page' : undefined"
:class="itemClassName"
>
<slot />
<span
v-if="props.badge !== undefined"
class="min-w-4 rounded-full bg-newt-danger px-[5px] text-center text-[11px] font-bold leading-4 text-newt-on-accent"
>
{{ props.badge }}
</span>
</component>
</li>
</template>export { default as SideNav } from "./SideNav.vue"
export { default as SideNavGroup } from "./SideNavGroup.vue"
export { default as SideNavItem } from "./SideNavItem.vue"Update the import paths
The files import @/lib/utils and sibling components through the aliases in your components.json. Point them at wherever those live in your project.
No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Side Nav to your React project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.
No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Side Nav to your Vue project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.
Usage
import { SideNav } from "@/components/ui/side-nav"
export function Example() {
return <SideNav />
}<script setup lang="ts">
import { SideNav, SideNavGroup, SideNavItem } from "@/components/ui/side-nav"
</script>
<template>
<SideNav />
</template>API reference
SideNavGroup
label?string
The small heading over the group. Omit it for an unlabelled group.
stringSideNavItem
href?string
Makes the entry a link. Without it the entry is a button.
stringcurrent?boolean
Marks the section being shown.
booleanfalsevariant?"default" | "danger"
`danger` is for an entry that destroys something.
"default" | "danger""default"badge?number
A count shown at the end of the entry.
numberonClick / @click?(event) => void
Called when the entry is activated.
(event) => voidSideNav 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 installed with the library. Override a token and every component that reads it follows, including this one — see the token layer. In the plain HTML and CSS distribution the same component is newt-side-nav.
--newt-border--newt-text-muted--newt-radius-sm--newt-text-secondary--newt-font-sans--newt-duration-fast--newt-ease--newt-bg-hover--newt-text-primary--newt-bg-active--newt-text-link--newt-danger--newt-radius-full--newt-on-accent