Skip to content

ComponentsBlocks

SourceSource

Settings layout

A settings screen: grouped sections down the side and the chosen section's breadcrumb, heading and content beside them.

The frame of a settings area, assembled from a Side Nav and a Breadcrumb. You describe the sections as data and render the current one as the block’s content, so each section stays an ordinary component of yours.

Below 40rem the navigation moves above the content.

"use client"

import * as React from "react"

import {
  SettingsLayout,
  type SettingsGroup,
} from "@/registry/bases/newt/blocks/settings-layout/settings-layout"
import { Alert, AlertTitle } from "@/registry/bases/newt/ui/alert"
import { Button } from "@/registry/bases/newt/ui/button"
import {
  Field,
  FieldHelp,
  Input,
  Label,
  Switch,
} from "@/registry/bases/newt/ui/form-fields"

const GROUPS: readonly SettingsGroup[] = [
  {
    label: "Server",
    sections: [
      { id: "overview", label: "Overview" },
      { id: "roles", label: "Roles" },
    ],
  },
  {
    label: "Moderation",
    sections: [{ id: "audit-log", label: "Audit log", badge: 12 }],
  },
  { sections: [{ id: "delete", label: "Delete server", danger: true }] },
]

export default function SettingsLayoutDemo() {
  const [section, setSection] = React.useState("overview")
  const [saved, setSaved] = React.useState(false)

  return (
    <SettingsLayout
      title="Server settings"
      groups={GROUPS}
      section={section}
      onSectionChange={(next) => {
        setSection(next)
        setSaved(false)
      }}
    >
      {section === "overview" ? (
        <div className="flex max-w-sm flex-col gap-5">
          <Field>
            <Label htmlFor="settings-layout-name">Server name</Label>
            <Input id="settings-layout-name" defaultValue="Build Club" />
            <FieldHelp>Shown at the top of the channel list.</FieldHelp>
          </Field>
          <div className="flex items-center justify-between gap-4 text-sm text-newt-text-primary">
            <span id="settings-layout-welcome">Send a welcome message</span>
            <Switch aria-labelledby="settings-layout-welcome" defaultChecked />
          </div>
          {saved ? (
            <Alert variant="success">
              <AlertTitle>Changes saved</AlertTitle>
            </Alert>
          ) : null}
          <div>
            <Button onClick={() => setSaved(true)}>Save changes</Button>
          </div>
        </div>
      ) : (
        <p className="m-0 text-sm text-newt-text-secondary">
          This section is yours to fill in.
        </p>
      )}
    </SettingsLayout>
  )
}
<script setup lang="ts">
import { ref, watch } from "vue"
import {
  SettingsLayout,
  type SettingsGroup,
} from "~~/registry/bases/newt/blocks/settings-layout"
import { Alert, AlertTitle } from "~~/registry/bases/newt/ui/alert"
import { Button } from "~~/registry/bases/newt/ui/button"
import {
  Field,
  FieldHelp,
  Input,
  Label,
  Switch,
} from "~~/registry/bases/newt/ui/form-fields"

const GROUPS: readonly SettingsGroup[] = [
  {
    label: "Server",
    sections: [
      { id: "overview", label: "Overview" },
      { id: "roles", label: "Roles" },
    ],
  },
  {
    label: "Moderation",
    sections: [{ id: "audit-log", label: "Audit log", badge: 12 }],
  },
  { sections: [{ id: "delete", label: "Delete server", danger: true }] },
]

const section = ref("overview")
const name = ref("Build Club")
const welcome = ref(true)
const saved = ref(false)

watch(section, () => {
  saved.value = false
})
</script>

<template>
  <SettingsLayout
    v-model:section="section"
    title="Server settings"
    :groups="GROUPS"
  >
    <div v-if="section === 'overview'" class="flex max-w-sm flex-col gap-5">
      <Field>
        <Label for="settings-layout-name">Server name</Label>
        <Input id="settings-layout-name" v-model="name" />
        <FieldHelp>Shown at the top of the channel list.</FieldHelp>
      </Field>
      <div
        class="flex items-center justify-between gap-4 text-sm text-newt-text-primary"
      >
        <span id="settings-layout-welcome">Send a welcome message</span>
        <Switch v-model="welcome" aria-labelledby="settings-layout-welcome" />
      </div>
      <Alert v-if="saved" variant="success">
        <AlertTitle>Changes saved</AlertTitle>
      </Alert>
      <div>
        <Button @click="saved = true">Save changes</Button>
      </div>
    </div>
    <p v-else class="m-0 text-sm text-newt-text-secondary">
      This section is yours to fill in.
    </p>
  </SettingsLayout>
</template>

Installation

npx newtui@latest add settings-layoutnpx shadcn@latest add @newtui/settings-layoutnpx shadcn-vue@latest add @newtui/settings-layoutpnpm dlx newtui@latest add settings-layoutpnpm dlx shadcn@latest add @newtui/settings-layoutpnpm dlx shadcn-vue@latest add @newtui/settings-layoutyarn dlx newtui@latest add settings-layoutyarn dlx shadcn@latest add @newtui/settings-layoutyarn dlx shadcn-vue@latest add @newtui/settings-layoutbunx newtui@latest add settings-layoutbunx shadcn@latest add @newtui/settings-layoutbunx shadcn-vue@latest add @newtui/settings-layoutdeno run -A npm:newtui@latest add settings-layoutdeno run -A npm:shadcn@latest add @newtui/settings-layoutdeno run -A npm:shadcn-vue@latest add @newtui/settings-layoutvlx newtui@latest add settings-layoutvlx shadcn@latest add @newtui/settings-layoutvlx shadcn-vue@latest add @newtui/settings-layoutvp dlx newtui@latest add settings-layoutvp dlx shadcn@latest add @newtui/settings-layoutvp dlx shadcn-vue@latest add @newtui/settings-layoutnubx newtui@latest add settings-layoutnubx shadcn@latest add @newtui/settings-layoutnubx shadcn-vue@latest add @newtui/settings-layoutnlx newtui@latest add settings-layoutnlx shadcn@latest add @newtui/settings-layoutnlx shadcn-vue@latest add @newtui/settings-layoutupx newtui@latest add settings-layoutupx shadcn@latest add @newtui/settings-layoutupx shadcn-vue@latest add @newtui/settings-layout

The shadcn CLI needs the @newtui registry in your components.json. Set it up.

Add the components it builds on

Copy the source into your project

"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { Breadcrumb, BreadcrumbItem } from "@/registry/bases/newt/ui/breadcrumb"
import {
  SideNav,
  SideNavGroup,
  SideNavItem,
} from "@/registry/bases/newt/ui/side-nav"

/*
 * The shape the layout reads. A block does not know your router; map your
 * sections onto this at the edge of it.
 */
export interface SettingsSection {
  id: string
  label: string
  /** A count shown beside the entry. */
  badge?: number
  /** For an entry that destroys something. It is never the current section. */
  danger?: boolean
}

export interface SettingsGroup {
  /** The small heading over the group. */
  label?: string
  sections: readonly SettingsSection[]
}

export interface SettingsLayoutProps extends Omit<
  React.ComponentProps<"div">,
  "title"
> {
  /** What is being configured; the first crumb and the nav's name. */
  title: string
  groups: readonly SettingsGroup[]
  /** The id of the section being shown. */
  section: string
  onSectionChange?: (section: string) => void
}

/*
 * A settings screen: the list of sections down the side, and the chosen
 * section's heading, breadcrumb and content beside it. The content is the
 * children, so each section stays an ordinary component of yours. The
 * content column is a plain box and not a `<main>`, because the page the
 * block is dropped into has one already. Below 40rem the navigation moves
 * above the content.
 */
export function SettingsLayout({
  title,
  groups,
  section,
  onSectionChange,
  className,
  children,
  ...props
}: SettingsLayoutProps) {
  const current = groups
    .flatMap((group) => group.sections)
    .find((each) => each.id === section)

  return (
    <div
      className={cn(
        "flex w-full flex-col bg-newt-bg-elevated sm:flex-row",
        className
      )}
      {...props}
    >
      <SideNav
        aria-label={title}
        className="shrink-0 bg-newt-bg-surface px-2 sm:w-56"
      >
        {groups.map((group, index) => (
          <SideNavGroup key={group.label ?? index} label={group.label}>
            {group.sections.map((each) => (
              <SideNavItem
                key={each.id}
                badge={each.badge}
                variant={each.danger ? "danger" : "default"}
                current={!each.danger && each.id === section}
                onClick={() => onSectionChange?.(each.id)}
              >
                {each.label}
              </SideNavItem>
            ))}
          </SideNavGroup>
        ))}
      </SideNav>
      <div className="flex min-w-0 flex-1 flex-col gap-4 p-6">
        <Breadcrumb>
          <BreadcrumbItem>{title}</BreadcrumbItem>
          <BreadcrumbItem current>{current?.label ?? section}</BreadcrumbItem>
        </Breadcrumb>
        <h2 className="m-0 text-xl font-semibold leading-6 text-newt-text-primary">
          {current?.label ?? section}
        </h2>
        {children}
      </div>
    </div>
  )
}
<script setup lang="ts">
import { computed, type HTMLAttributes } from "vue"
import {
  Breadcrumb,
  BreadcrumbItem,
} from "~~/registry/bases/newt/ui/breadcrumb"
import {
  SideNav,
  SideNavGroup,
  SideNavItem,
} from "~~/registry/bases/newt/ui/side-nav"

import { cn } from "@/lib/utils"

import type { SettingsGroup } from "./types"

/*
 * A settings screen: the list of sections down the side, and the chosen
 * section's heading, breadcrumb and content beside it. The content is the
 * default slot, so each section stays an ordinary component of yours. The
 * content column is a plain box and not a `<main>`, because the page the
 * block is dropped into has one already. Below 40rem the navigation moves
 * above the content.
 */
const props = defineProps<{
  class?: HTMLAttributes["class"]
  /** What is being configured; the first crumb and the nav's name. */
  title: string
  groups: readonly SettingsGroup[]
}>()

/** The id of the section being shown. */
const section = defineModel<string>("section", { required: true })

const current = computed(() =>
  props.groups
    .flatMap((group) => group.sections)
    .find((each) => each.id === section.value)
)
</script>

<template>
  <div
    :class="
      cn('flex w-full flex-col bg-newt-bg-elevated sm:flex-row', props.class)
    "
  >
    <SideNav
      :aria-label="props.title"
      class="shrink-0 bg-newt-bg-surface px-2 sm:w-56"
    >
      <SideNavGroup
        v-for="(group, index) in props.groups"
        :key="group.label ?? index"
        :label="group.label"
      >
        <SideNavItem
          v-for="each in group.sections"
          :key="each.id"
          :badge="each.badge"
          :variant="each.danger ? 'danger' : 'default'"
          :current="!each.danger && each.id === section"
          @click="section = each.id"
        >
          {{ each.label }}
        </SideNavItem>
      </SideNavGroup>
    </SideNav>
    <div class="flex min-w-0 flex-1 flex-col gap-4 p-6">
      <Breadcrumb>
        <BreadcrumbItem>{{ props.title }}</BreadcrumbItem>
        <BreadcrumbItem current>{{ current?.label ?? section }}</BreadcrumbItem>
      </Breadcrumb>
      <h2 class="m-0 text-xl font-semibold leading-6 text-newt-text-primary">
        {{ current?.label ?? section }}
      </h2>
      <slot />
    </div>
  </div>
</template>
/*
 * The shape the layout reads. A block does not know your router; map your
 * sections onto this at the edge of it.
 */
export interface SettingsSection {
  id: string
  label: string
  /** A count shown beside the entry. */
  badge?: number
  /** For an entry that destroys something. It is never the current section. */
  danger?: boolean
}

export interface SettingsGroup {
  /** The small heading over the group. */
  label?: string
  sections: readonly SettingsSection[]
}
export { default as SettingsLayout } from "./SettingsLayout.vue"
export type { SettingsGroup, SettingsSection } from "./types"

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 Settings layout 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 Settings layout 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 { SettingsLayout } from "@/components/settings-layout"

export function Example() {
  return <SettingsLayout />
}
<script setup lang="ts">
import { SettingsLayout } from "@/components/settings-layout"
</script>

<template>
  <SettingsLayout />
</template>

API reference

SettingsLayout

PropType
title?string

What is being configured. It is the first crumb and the name of the navigation.

Typestring
groups?{ label?: string; sections: SettingsSection[] }[]

The sections, in groups. A section is `{ id, label, badge?, danger? }`.

Type{ label?: string; sections: SettingsSection[] }[]
section / v-model:section?string

The id of the section being shown.

Typestring
onSectionChange?(section: string) => void

React only. Called when an entry is chosen; Vue emits `update:section`.

Type(section: string) => void
children / default slot?React.ReactNode / Vue slot

The content of the current section.

TypeReact.ReactNode / Vue slot

The entries are buttons, because the block swaps content in place. In a routed app, copy the block and give each SideNavItem an href.

Accessibility

The navigation is a landmark named by title. The content column is a plain box, so put the block inside your page’s own <main>. The current section carries aria-current="page" in the navigation and is repeated as the breadcrumb’s last crumb and as the heading above the content.

Tokens

Settings layout 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.