Screen

Settings

Searchable multi-page settings shell with responsive navigation and accessible control groups.

General

Permissions

Default permissions

Allow the app to read and edit files in its workspace and request additional access when needed.

Auto-review

Automatically review requests for additional access and flag elevated risks before continuing.

Full access

Allow editing files across your computer and running commands with network access.

General

Default file open destination

Choose where files and folders open by default.

Language

Language used throughout the app interface.

Bottom panel

Show the bottom panel control in the app header.

Composition

Rendered settings shell

<SettingsBlock>
- <SidebarProvider>
  - <Sidebar>
    - search
    - page navigation
    </Sidebar>
  - <SidebarInset>
    - back action
      - <SettingsBackAction />
    - active page content
      - <FieldSet>
        <FieldLegend />
        <FieldGroup>
        <Field />
        </FieldGroup>
        </FieldSet>
    </SidebarInset>
  </SidebarProvider>
</SettingsBlock>

Installation

Registry command

npx shadcn@latest add https://control-ui.dev/r/settings-block.json

See registry manifest

Usage

"use client";

import { SettingsIcon, SparklesIcon } from "lucide-react";

import { useState } from "react";

import { SettingsBackAction, SettingsBlock, type SettingsPageDefinition } from "@/components/control-ui/blocks/settings";

import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/control-ui/ui/select";

import { Switch } from "@/components/control-ui/ui/switch";

const themeLabels: Record<string, string> = {

system: "System",

light: "Light",

dark: "Dark",

};

export default function SettingsPage() {

const [notifications, setNotifications] = useState(true);

const [theme, setTheme] = useState("system");

const pages: readonly SettingsPageDefinition[] = [

{

id: "general",

title: "General",

icon: <SettingsIcon />,

sections: [

{

id: "preferences",

title: "Preferences",

settings: [

{

id: "notifications",

title: "Notifications",

description: "Receive an alert when a background run finishes.",

keywords: ["alerts", "background"],

              renderControl: (props) => <Switch {...props} checked={notifications} onCheckedChange={setNotifications} />,

},

],

},

],

},

{

id: "appearance",

title: "Appearance",

icon: <SparklesIcon />,

sections: [

{

id: "theme",

title: "Theme",

settings: [

{

id: "color-mode",

title: "Color mode",

description: "Choose how the interface follows your system appearance.",

renderControl: (props) => (

<Select value={theme} onValueChange={setTheme}>

<SelectTrigger {...props}>

<SelectValue>{(value) => themeLabels[value] ?? value}</SelectValue>

</SelectTrigger>

<SelectContent>

<SelectItem value="system">System</SelectItem>

<SelectItem value="light">Light</SelectItem>

<SelectItem value="dark">Dark</SelectItem>

</SelectContent>

</Select>

),

},

],

},

],

},

];

return <SettingsBlock pages={pages} backAction={<SettingsBackAction />} />;

}

Library dependencies

ButtonbuttonComponent EmptyemptyComponent FieldfieldComponent InputinputComponent Input groupinput-groupComponent Live statuslive-statusComponent Scroll areascroll-areaComponent SidebarsidebarComponent TypographytypographyComponent

Owned source

This template’s recipe and private support files. Public dependencies stay linked above.

Block recipesrc/registry/blocks/control-ui/settings.tsx

Settings datasrc/registry/blocks/control-ui/settings-data.ts

Motionsrc/registry/lib/motion.ts

src/registry/blocks/control-ui/settings.tsx

"use client";

import { ArrowLeftIcon, SearchIcon, XIcon } from "lucide-react";

import type { ComponentProps, ReactNode } from "react";

import { useEffect, useId, useState } from "react";

import { cn } from "@/components/control-ui/lib/cn";

import { prefersReducedMotion } from "@/components/control-ui/lib/motion";

import { Button } from "@/components/control-ui/ui/button";

import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "@/components/control-ui/ui/empty";

import {

Field,

FieldContent,

FieldDescription,

FieldGroup,

FieldLabel,

FieldLegend,

FieldSeparator,

FieldSet,

} from "@/components/control-ui/ui/field";

import { Input } from "@/components/control-ui/ui/input";

import { InputGroup, InputGroupAddon } from "@/components/control-ui/ui/input-group";

import { LiveStatus } from "@/components/control-ui/ui/live-status";

import { ScrollArea } from "@/components/control-ui/ui/scroll-area";

import {

Sidebar,

SidebarContent,

SidebarGroup,

SidebarGroupLabel,

SidebarHeader,

SidebarInset,

SidebarMenu,

SidebarMenuButton,

SidebarMenuItem,

SidebarProvider,

type SidebarProviderProps,

type SidebarStyle,

SidebarTrigger,

useSidebar,

} from "@/components/control-ui/ui/sidebar";

import { Heading, Text } from "@/components/control-ui/ui/typography";

import {

type SettingDefinition,

type SettingsControlProps,

type SettingsPageDefinition,

type SettingsSearchResult,

searchSettings,

} from "./settings-data";

export type { SettingDefinition, SettingsControlProps, SettingsPageDefinition, SettingsSectionDefinition } from "./settings-data";

export type SettingsBlockProps = Omit<ComponentProps<"div">, "children"> &

Pick<SidebarProviderProps, "persistOpen" | "keyboardShortcut"> & {

pages: readonly SettingsPageDefinition[];

activePageId?: string;

defaultActivePageId?: string;

onActivePageChange?: (pageId: string) => void;

backAction?: ReactNode;

searchPlaceholder?: string;

searchLabel?: string;

layout?: "viewport" | "contained";

};

type PendingTarget = {

pageId: string;

rowId: string;

controlId: string;

};

export function SettingsBlock({

pages,

activePageId,

defaultActivePageId,

onActivePageChange,

backAction,

searchPlaceholder = "Search settings",

searchLabel = "Search settings",

layout = "viewport",

className,

style,

...props

}: SettingsBlockProps) {

const [internalPageId, setInternalPageId] = useState(defaultActivePageId ?? pages[0]?.id);

const [query, setQuery] = useState("");

const [pendingTarget, setPendingTarget] = useState<PendingTarget | null>(null);

const instanceId = useId();

const requestedPageId = activePageId ?? internalPageId;

const currentPage = pages.find((page) => page.id === requestedPageId) ?? pages[0];

const results = searchSettings(pages, query);

function changePage(pageId: string) {

if (activePageId === undefined) setInternalPageId(pageId);

onActivePageChange?.(pageId);

}

const providerStyle: SidebarStyle = { "--sidebar-width": "15.5rem", ...style };

return (

<SidebarProvider

layout={layout}

className={cn("bg-background text-foreground", layout === "viewport" && "h-svh overflow-hidden", className)}

style={providerStyle}

{...props}

>

<SettingsShell

pages={pages}

currentPage={currentPage}

query={query}

results={results}

backAction={backAction}

searchPlaceholder={searchPlaceholder}

searchLabel={searchLabel}

instanceId={instanceId}

pendingTarget={pendingTarget}

onPendingTargetChange={setPendingTarget}

onPageChange={changePage}

onQueryChange={setQuery}

/>

</SidebarProvider>

);

}

function SettingsShell({

pages,

currentPage,

query,

results,

backAction,

searchPlaceholder,

searchLabel,

instanceId,

pendingTarget,

onPendingTargetChange,

onPageChange,

onQueryChange,

}: {

pages: readonly SettingsPageDefinition[];

currentPage?: SettingsPageDefinition;

query: string;

results: readonly SettingsSearchResult[];

backAction?: ReactNode;

searchPlaceholder: string;

searchLabel: string;

instanceId: string;

pendingTarget: PendingTarget | null;

onPendingTargetChange: (target: PendingTarget | null) => void;

onPageChange: (pageId: string) => void;

onQueryChange: (query: string) => void;

}) {

const { setOpenMobile } = useSidebar();

useEffect(() => {

if (!pendingTarget || currentPage?.id !== pendingTarget.pageId) return;

const frame = requestAnimationFrame(() => {

const row = document.getElementById(pendingTarget.rowId);

const control = document.getElementById(pendingTarget.controlId);

row?.scrollIntoView({ block: "center", behavior: prefersReducedMotion(row) ? "auto" : "smooth" });

(control instanceof HTMLElement ? control : row)?.focus({ preventScroll: true });

onPendingTargetChange(null);

});

return () => cancelAnimationFrame(frame);

}, [currentPage?.id, onPendingTargetChange, pendingTarget]);

function navigate(pageId: string) {

onPageChange(pageId);

setOpenMobile(false);

}

function openResult(result: SettingsSearchResult) {

const ids = settingDomIds(instanceId, result.page.id, result.section.id, result.setting.id);

onPendingTargetChange({ pageId: result.page.id, rowId: ids.row, controlId: ids.control });

navigate(result.page.id);

}

const trimmedQuery = query.trim();

const resultCount = `${results.length} ${results.length === 1 ? "setting" : "settings"} found`;

const searchStatus = results.length > 0 ? resultCount : "No matching settings";

return (

<>

<LiveStatus message={trimmedQuery ? searchStatus : ""} />

<Sidebar collapsible="offcanvas">

<SidebarHeader className="gap-3 border-b border-sidebar-border p-3">

{backAction ? <div className="min-w-0">{backAction}</div> : null}

          <SettingsSearch value={query} label={searchLabel} placeholder={searchPlaceholder} onValueChange={onQueryChange} />

</SidebarHeader>

<SidebarContent>

{trimmedQuery ? (

<SettingsSearchNavigation results={results} onSelect={openResult} onClear={() => onQueryChange("")} />

) : (

<SettingsPageNavigation pages={pages} activePageId={currentPage?.id} onSelect={navigate} />

)}

</SidebarContent>

</Sidebar>

<SidebarInset className="h-full min-h-0 min-w-0">

<header className="flex h-12 shrink-0 items-center gap-2 border-b px-3 lg:hidden">

<SidebarTrigger />

<Text size="label" weight="medium" className="truncate" title={currentPage?.title}>

{currentPage?.title ?? "Settings"}

</Text>

</header>

<ScrollArea className="min-h-0 flex-1" lockAxis="x">

{currentPage ? (

<SettingsPage page={currentPage} instanceId={instanceId} />

) : (

<SettingsEmpty title="No settings" description="Add a settings page to populate this space." />

)}

</ScrollArea>

</SidebarInset>

</>

);

}

function SettingsSearch({

value,

label,

placeholder,

onValueChange,

}: {

value: string;

label: string;

placeholder: string;

onValueChange: (value: string) => void;

}) {

return (

<InputGroup size="sm">

<InputGroupAddon className="ps-2.5">

<SearchIcon className="size-3.5" aria-hidden="true" />

</InputGroupAddon>

<Input

type="search"

aria-label={label}

placeholder={placeholder}

value={value}

onChange={(event) => onValueChange(event.currentTarget.value)}

/>

{value ? (

        <Button variant="ghost" size="xs" iconOnly aria-label="Clear settings search" className="me-1" onClick={() => onValueChange("")}>

<XIcon className="size-3.5" aria-hidden="true" />

</Button>

) : null}

</InputGroup>

);

}

function SettingsPageNavigation({

pages,

activePageId,

onSelect,

}: {

pages: readonly SettingsPageDefinition[];

activePageId?: string;

onSelect: (pageId: string) => void;

}) {

return (

<SidebarGroup>

<SidebarGroupLabel>Settings</SidebarGroupLabel>

<SidebarMenu>

{pages.map((page) => (

<SidebarMenuItem key={page.id}>

<SidebarMenuButton size="sm" isActive={page.id === activePageId} onClick={() => onSelect(page.id)}>

{page.icon}

<span>{page.title}</span>

</SidebarMenuButton>

</SidebarMenuItem>

))}

</SidebarMenu>

</SidebarGroup>

);

}

function SettingsSearchNavigation({

results,

onSelect,

onClear,

}: {

results: readonly SettingsSearchResult[];

onSelect: (result: SettingsSearchResult) => void;

onClear: () => void;

}) {

if (results.length === 0) {

return (

<SettingsEmpty

title="No matching settings"

description="Try another name or keyword."

action={

<Button variant="surface" size="sm" onClick={onClear}>

Clear search

</Button>

}

/>

);

}

const groups = new Map<string, { page: SettingsPageDefinition; results: SettingsSearchResult[] }>();

for (const result of results) {

const group = groups.get(result.page.id) ?? { page: result.page, results: [] };

group.results.push(result);

groups.set(result.page.id, group);

}

return (

<>

{[...groups.values()].map((group) => (

<SidebarGroup key={group.page.id}>

<SidebarGroupLabel>

{group.page.icon}

<span>{group.page.title}</span>

</SidebarGroupLabel>

<SidebarMenu>

{group.results.map((result) => (

                <SidebarMenuButton size="sm" className="h-auto min-h-(--control-h-sm) py-1.5" onClick={() => onSelect(result)}>

<span title={result.setting.title}>{result.setting.title}</span>

</SidebarMenuButton>

</SidebarMenuItem>

))}

</SidebarMenu>

</SidebarGroup>

))}

</>

);

}

function SettingsPage({ page, instanceId }: { page: SettingsPageDefinition; instanceId: string }) {

const { layout } = useSidebar();

return (

<div className="mx-auto flex w-full max-w-4xl flex-col gap-10 px-5 py-8 md:px-10 md:py-12">

<Heading level={layout === "contained" ? 2 : 1} size="heading-2">

{page.title}

</Heading>

{page.sections.map((section) => (

<FieldSet key={section.id} className="gap-3">

<FieldLegend className="text-body font-semibold">{section.title}</FieldLegend>

<FieldGroup className="gap-0 overflow-hidden rounded-[var(--radius-lg)] border bg-card">

{section.settings.map((setting, index) => (

<SettingsRow

key={setting.id}

pageId={page.id}

sectionId={section.id}

setting={setting}

instanceId={instanceId}

separated={index > 0}

/>

))}

</FieldGroup>

</FieldSet>

))}

</div>

);

}

function SettingsRow({

pageId,

sectionId,

setting,

instanceId,

separated,

}: {

pageId: string;

sectionId: string;

setting: SettingDefinition;

instanceId: string;

separated: boolean;

}) {

const ids = settingDomIds(instanceId, pageId, sectionId, setting.id);

const controlProps: SettingsControlProps = {

id: ids.control,

"aria-labelledby": ids.label,

"aria-describedby": setting.description ? ids.description : undefined,

};

return (

<>

{separated ? <FieldSeparator /> : null}

<Field

id={ids.row}

orientation="responsive"

tabIndex={-1}

        className="scroll-m-8 gap-3 p-4 outline-none transition-colors duration-[var(--duration-fast)] focus:bg-foreground/4 focus-within:bg-foreground/4"

>

<FieldContent>

<FieldLabel id={ids.label} htmlFor={ids.control} className="leading-snug">

{setting.title}

</FieldLabel>

{setting.description ? <FieldDescription id={ids.description}>{setting.description}</FieldDescription> : null}

</FieldContent>

<div className="flex shrink-0 items-center">{setting.renderControl(controlProps)}</div>

</Field>

</>

);

}

function SettingsEmpty({ title, description, action }: { title: string; description: string; action?: ReactNode }) {

return (

<Empty className="min-h-40 gap-3 p-4">

<EmptyHeader>

<EmptyMedia className="mb-0 size-8">

<SearchIcon className="size-4" aria-hidden="true" />

</EmptyMedia>

<EmptyTitle>{title}</EmptyTitle>

<EmptyDescription>{description}</EmptyDescription>

</EmptyHeader>

{action ? <EmptyContent>{action}</EmptyContent> : null}

</Empty>

);

}

function settingDomIds(instanceId: string, pageId: string, sectionId: string, settingId: string) {

  const base = [instanceId, pageId, sectionId, settingId].map((value) => value.replace(/[^a-zA-Z0-9_-]/g, "-")).join("-");

return {

row: `${base}-row`,

control: `${base}-control`,

label: `${base}-label`,

description: `${base}-description`,

};

}

export function SettingsBackAction({

children = "Back to app",

...props

}: Omit<ComponentProps<typeof Button>, "children"> & { children?: ReactNode }) {

return (

<Button variant="quiet" size="sm" className="-ms-1 justify-start gap-2" {...props}>

<ArrowLeftIcon className="size-4" data-icon-dir="inline" aria-hidden="true" />

{children}

</Button>

);

}