Skip to content

ComponentsActions

SourceSource

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.

Root class 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

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

PropType
label?string

The small heading over the group. Omit it for an unlabelled group.

Typestring

SideNavItem

PropType
href?string

Makes the entry a link. Without it the entry is a button.

Typestring
current?boolean

Marks the section being shown.

Typeboolean
Defaultfalse
variant?"default" | "danger"

`danger` is for an entry that destroys something.

Type"default" | "danger"
Default"default"
badge?number

A count shown at the end of the entry.

Typenumber
onClick / @click?(event) => void

Called when the entry is activated.

Type(event) => void

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 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