{
"slug": "hook-sidebar",
"name": "Hook Sidebar",
"description": "Collapsible navigation sidebar with animated traveling spring rail and curved elbow hook.",
"summary": "A precision navigation rail engineered for documentation portals, administrative sidebars, and hierarchical application navigators. Features a continuous vertical guide rail with a dynamic traveling SVG elbow hook that smoothly tracks the active or hovered navigation item via real-time DOM geometry measurement (offsetTop + offsetHeight / 2) and high-frequency ResizeObserver listeners.",
"category": "navigation",
"tags": [
"sidebar",
"navigation",
"hook",
"rail",
"spring",
"a11y"
],
"dependencies": [
"clsx",
"tailwind-merge",
"motion",
"next"
],
"version": "1.0.0",
"createdDate": "2026-09-20",
"updatedDate": "2026-09-20",
"interactive": true,
"supportsColor": true,
"highlights": [
"Continuous SVG vector path interpolation (M0.5 0a6 6 0 0 0 6 6H12) with 6px corner curve",
"Real-time DOM element measuring with ResizeObserver and requestAnimationFrame",
"Dual rails: a spring-animated hover and focus preview rail and a persistent active indicator",
"Active item follows Next.js usePathname() for exact href matches; \"#\" hrefs only update the selection",
"Integrated prefers-reduced-motion fallback bypassing physics for instant transitions"
],
"anatomy": [
"\n );\n}\n",
"content": "\"use client\";\n\nimport { useEffect, useRef, useState, type ComponentProps } from \"react\";\nimport Link from \"next/link\";\nimport { usePathname } from \"next/navigation\";\nimport { motion, useReducedMotion } from \"motion/react\";\nimport { cn } from \"@/lib/utils\";\n\nconst CORNER = 6;\nconst DASH =\n \"repeating-linear-gradient(to top, transparent 0 2px, currentColor 2px 4px)\";\n\nexport type HookSidebarItem =\n | string\n | {\n label: string;\n href?: string;\n onClick?: (e: React.MouseEvent) => void;\n };\n\nexport type HookSidebarProps = Omit, \"onChange\"> & {\n items: HookSidebarItem[];\n label?: string;\n value?: number;\n defaultValue?: number;\n onChange?: (index: number) => void;\n color?: string;\n dashed?: boolean;\n};\n\nconst hrefOf = (item: HookSidebarItem) =>\n typeof item === \"string\" ? undefined : item.href;\n\nconst labelOf = (item: HookSidebarItem) =>\n typeof item === \"string\" ? item : item.label;\n\nconst Rail = ({\n from = 0,\n y,\n visible,\n color,\n dashed,\n className,\n}: {\n from?: number;\n y: number | null;\n visible: boolean;\n color?: string;\n dashed: boolean;\n className?: string;\n}) => {\n const reduced = useReducedMotion();\n const travel = reduced\n ? { duration: 0 }\n : { type: \"spring\" as const, stiffness: 420, damping: 34, mass: 0.7 };\n\n return (\n \n \n \n \n \n \n );\n};\n\nexport function HookSidebar({\n items,\n label,\n value,\n defaultValue = 0,\n onChange,\n color = \"#FC4C01\",\n dashed = true,\n className,\n ...props\n}: HookSidebarProps) {\n const pathname = usePathname();\n const listRef = useRef(null);\n const itemRefs = useRef<(HTMLElement | null)[]>([]);\n const [centers, setCenters] = useState([]);\n const [internalValue, setInternalValue] = useState(defaultValue);\n const [hoverIndex, setHoverIndex] = useState(null);\n const [pointerInside, setPointerInside] = useState(false);\n const [focusInside, setFocusInside] = useState(false);\n\n const routeIndex = items.findIndex((item) => hrefOf(item) === pathname);\n const activeIndex = value ?? (routeIndex >= 0 ? routeIndex : internalValue);\n\n useEffect(() => {\n const list = listRef.current;\n if (!list) return;\n\n const measure = () =>\n setCenters(\n itemRefs.current.map((el) =>\n el ? el.offsetTop + el.offsetHeight / 2 : 0,\n ),\n );\n\n measure();\n const rafId = requestAnimationFrame(measure);\n const observer = new ResizeObserver(measure);\n observer.observe(list);\n return () => {\n cancelAnimationFrame(rafId);\n observer.disconnect();\n };\n }, [items.length]);\n\n const activeY = activeIndex < 0 ? null : (centers[activeIndex] ?? null);\n const hoverY = hoverIndex === null ? null : (centers[hoverIndex] ?? null);\n\n const hoverFrom =\n activeY !== null && hoverY !== null && hoverY <= activeY\n ? Math.max(0, hoverY - CORNER)\n : (activeY ?? 0);\n\n const select = (index: number) => {\n if (value === undefined) setInternalValue(index);\n onChange?.(index);\n };\n\n return (\n \n {label && (\n \n {label}\n \n )}\n\n setPointerInside(false)}\n className=\"relative flex flex-col gap-0.5\"\n >\n \n \n\n {items.map((item, index) => {\n const text = labelOf(item);\n const href = hrefOf(item);\n const isActive = index === activeIndex;\n const setRef = (el: HTMLElement | null) => {\n itemRefs.current[index] = el;\n };\n const rowProps = {\n \"data-slot\": \"hook-sidebar-item\",\n \"data-active\": isActive,\n onMouseEnter: () => {\n setHoverIndex(index);\n setPointerInside(true);\n },\n onFocus: () => {\n setHoverIndex(index);\n setFocusInside(true);\n },\n onBlur: () => setFocusInside(false),\n onClick: (e: React.MouseEvent) => {\n if (typeof item !== \"string\" && item.onClick) {\n item.onClick(e);\n }\n if (href?.startsWith(\"#\")) {\n e.preventDefault();\n }\n select(index);\n },\n className: cn(\n \"rounded-lg py-1 pl-5 pr-2 text-left text-xs transition-colors duration-200 motion-reduce:transition-none select-none cursor-pointer\",\n isActive\n ? \"text-zinc-950 font-semibold dark:text-white dark:font-medium\"\n : \"text-zinc-600 hover:text-zinc-950 dark:text-zinc-400 dark:hover:text-zinc-200\",\n ),\n };\n\n return href ? (\n \n {text}\n \n ) : (\n \n {text}\n \n );\n })}\n \n \n );\n}\n",
"type": "registry:ui",
"target": "@ui/hook-sidebar.tsx"
}
],
"type": "registry:ui",
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"title": "Hook Sidebar"
}