shadcn-syntax-layout-primitives

name	shadcn-syntax-layout-primitives
description	Use when adding, debugging, or refactoring any of the four shadcn ui layout-helper primitives : Resizable (drag-to-resize split panes), ScrollArea (custom-styled scrollable region with a Radix scrollbar), Separator (horizontal or vertical divider), or AspectRatio (lock a container to a width:height ratio like 16/9, 1/1, 9/16). Composes the right subcomponents per primitive (ResizablePanelGroup / ResizablePanel / ResizableHandle ; ScrollArea / ScrollBar ; Separator with orientation + decorative ; AspectRatio with ratio), wires their prop surfaces against the underlying libraries (react-resizable-panels v4 for Resizable, Radix UI for ScrollArea / Separator / AspectRatio), and explains the `"use client"` story per primitive (all four ship with `"use client"` in the v4 registry source, contrary to the "pure-styling = server-safe" rumor). Prevents the canonical layout-helper failures : rendering a ResizablePanel outside a ResizablePanelGroup so react-resizable- panels crashes ("Panel components must be rendered within a PanelGroup container"), giving a ScrollArea no explicit height so the viewport never overflows and the custom scrollbar never appears, omitting `orientation="vertical"` on a Separator inside a row layout so the default horizontal `h-px` div collapses to zero, putting an absolutely-positioned child inside an AspectRatio without `inset-0` so the ratio container is empty, and nesting multiple ResizablePanelGroups in the same handle-id namespace so drag state leaks across groups. Covers the four shadcn primitives verbatim from `apps/v4/registry/new-york-v4/ui/{resizable,scroll-area,separator, aspect-ratio}.tsx`, the v4 `orientation` rename on PanelGroup (no longer `direction`), the v4 `onLayoutChange` rename (no longer `onLayout`), Panel-level `collapsible` + `collapsedSize` + `onCollapse` + `onExpand`, the `autoSaveId` localStorage persistence pattern, `ResizableHandle withHandle` for the visible grip, the ScrollArea auto-vertical-scrollbar (no need to compose ScrollBar for vertical scroll, only for horizontal or when both axes are needed), the Radix Separator `decorative` accessibility flag (true = `role="none"`, false = `role="separator"`), and the AspectRatio inset-0 child pattern. Keywords: shadcn layout primitives, shadcn resizable, resizable panels, ResizablePanelGroup, ResizablePanel, ResizableHandle, split pane, splitter, drag to resize, react-resizable-panels, PanelGroup orientation, defaultSize, minSize, maxSize, collapsible panel, collapsedSize, autoSaveId, withHandle, shadcn scroll area, ScrollArea, ScrollBar, custom scrollbar, horizontal scrollbar, scroll area horizontal, Radix ScrollArea, scrollbar orientation, ScrollArea no scroll, ScrollArea fixed height, shadcn separator, Separator orientation horizontal, Separator orientation vertical, vertical divider, horizontal divider, decorative separator, role separator, shadcn aspect ratio, AspectRatio, 16/9 container, 1/1 square, 9/16 portrait, video container, image container, iframe container, responsive media, how do I make resizable panels, how do I add a vertical divider, how do I lock a video to 16:9, why is my scroll area not scrolling, why is my separator invisible, Panel must be rendered within a PanelGroup, ScrollArea no overflow, layout helpers, divider, split pane, splitter.
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui : Layout Primitives

Four shadcn primitives ship as pure layout helpers. They hold no business state and expose no independent decision logic. They differ only in which layout problem they solve : drag-to-resize panes, custom-styled scroll, content divider, fixed width:height ratio. Pick by the layout problem and compose. This skill covers all four because none of them is large enough to warrant a dedicated skill, and the composition rules are isolated per primitive.

Quick Reference

The four primitives

Primitive	Solves	Library	Subcomponents	"use client" in v4 source
Resizable	Drag-to-resize split panes	react-resizable-panels v4	ResizablePanelGroup, ResizablePanel, ResizableHandle	YES
ScrollArea	Custom-styled scrollable region	Radix ScrollArea	ScrollArea, ScrollBar	YES
Separator	Horizontal or vertical divider	Radix Separator	Separator	YES
AspectRatio	Lock container to width:height ratio	Radix AspectRatio	AspectRatio	YES

Decision tree : Which primitive?

Q. What layout problem do I have?
   Two or more regions, user drags a handle to resize them   -> Resizable
   A scroll region that needs styled scrollbars (or a thin,
   always-visible scrollbar that matches the theme)          -> ScrollArea
   Visual line dividing two content blocks (in a list, in
   a stack, between toolbar groups)                          -> Separator
   Element whose visible height must be a fixed fraction of
   its width (video, image, iframe, map embed, canvas)       -> AspectRatio

ALWAYS pick the primitive from the layout problem. NEVER pick AspectRatio for a generic flex / grid layout problem ; it freezes the ratio and absolutely-positions the child, which fights flex / grid layouts.

"use client" invariant

The v4 registry source for ALL FOUR primitives starts with . This is true even for and , which appear stateless. The directive is in the source because the file uses Radix primitives whose internals call React client hooks. NEVER strip from even if your linter suggests it is unused. Stripping it makes the file a Server Component, and Radix throws a "client hooks in server component" error at hydration.