Components

Dockable Panel

Experimental

Non-modal workspace panel that moves between two explicit edge slots with a mobile Drawer fallback.

Composition

Workspace panel

<DockablePanel>
- <DockablePanelHeader>
  - <DockablePanelDragHandle>
    - <DockablePanelTitle />
    </DockablePanelDragHandle>
  - <DockablePanelActions>
    - <DockablePanelDock />
    - <DockablePanelToggle />
    - <DockablePanelClose />
    </DockablePanelActions>
  </DockablePanelHeader>
- <DockablePanelContent />
</DockablePanel>

Installation

The Control UI source installs this primitive from src/registry/sources/control-ui/ui/dockable-panel.tsx.

Registry command

npx shadcn@latest add https://control-ui.dev/r/dockable-panel.json

See registry manifest

Dependencies

Docking geometrysrc/registry/sources/control-ui/ui/dockable-panel-geometry.tsSupport

Mobile hooksrc/registry/hooks/use-mobile.tsHook

ButtonbuttonPrimitive DrawerdrawerPrimitive Live statuslive-statusPrimitive Scroll areascroll-areaPrimitive SidebarsidebarPrimitive

Raw code

Primary installed source

src/registry/sources/control-ui/ui/dockable-panel.tsx

"use client";

import type {

ComponentProps,

CSSProperties,

KeyboardEvent as ReactKeyboardEvent,

ReactNode,

PointerEvent as ReactPointerEvent,

RefObject,

} from "react";

import { createContext, use, useEffect, useEffectEvent, useId, useRef, useState } from "react";

import { useIsMobile } from "@/components/control-ui/hooks/use-mobile";

import type { ButtonKnobStyle } from "@/components/control-ui/knob-contracts/button-knobs";

import type { DockablePanelKnobStyle } from "@/components/control-ui/knob-contracts/dockable-panel-knobs";

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

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

import { Drawer, DrawerBody, DrawerContent } from "@/components/control-ui/ui/drawer";

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

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

import {

clampDockablePanelPosition,

dockablePanelSideAt,

dockablePanelSideForKey,

oppositeDockablePanelSide,

} from "./dockable-panel-geometry";

export type DockablePanelPlacement = "left" | "right";

export type DockablePanelProps = Omit<ComponentProps<"aside">, "onChange" | "ref" | "style"> & {

open?: boolean;

defaultOpen?: boolean;

onOpenChange?: (open: boolean) => void;

placement?: DockablePanelPlacement;

defaultPlacement?: DockablePanelPlacement;

onPlacementChange?: (placement: DockablePanelPlacement) => void;

finalFocus?: RefObject<HTMLElement | null>;

style?: CSSProperties & DockablePanelKnobStyle;

};

export type DockablePanelHeaderProps = Omit<ComponentProps<"div">, "style"> & {

style?: CSSProperties & DockablePanelKnobStyle;

};

export type DockablePanelDragHandleProps = Omit<ComponentProps<"div">, "style"> & {

dragLabel?: string;

dockHintLabel?: string;

style?: CSSProperties & DockablePanelKnobStyle;

};

export type DockablePanelTitleProps = Omit<ComponentProps<"h2">, "style" | "id"> & {

style?: CSSProperties & DockablePanelKnobStyle;

};

export type DockablePanelActionsProps = ComponentProps<"div"> & { style?: CSSProperties & DockablePanelKnobStyle };

export type DockablePanelToggleProps = Omit<Omit<ComponentProps<"button">, "children"> & { children?: ReactNode }, "style"> & {

style?: CSSProperties & ButtonKnobStyle;

};

export type DockablePanelDockProps = Omit<

Omit<ComponentProps<"button">, "children"> & {

placement: DockablePanelPlacement;

children?: ReactNode;

},

"style"

> & { style?: CSSProperties & ButtonKnobStyle };

export type DockablePanelCloseProps = Omit<Omit<ComponentProps<"button">, "children"> & { children?: ReactNode }, "style"> & {

style?: CSSProperties & ButtonKnobStyle;

};

export type DockablePanelContentPadding = "default" | "none";

export type DockablePanelContentProps = ComponentProps<"div"> & {

padding?: DockablePanelContentPadding;

style?: CSSProperties & DockablePanelKnobStyle;

};

type DockablePanelContextValue = {

close: () => void;

isMobile: boolean;

placement: DockablePanelPlacement;

setPlacement: (placement: DockablePanelPlacement) => void;

togglePlacement: () => void;

titleId: string;

dragHandleProps: {

onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;

onPointerMove: (event: ReactPointerEvent<HTMLElement>) => void;

onPointerUp: (event: ReactPointerEvent<HTMLElement>) => void;

onPointerCancel: (event: ReactPointerEvent<HTMLElement>) => void;

};

const DockablePanelContext = createContext<DockablePanelContextValue | null>(null);

function useDockablePanelContext() {

const context = use(DockablePanelContext);

if (!context) throw new Error("DockablePanel parts must be used inside DockablePanel.");

return context;

}

function useControllableState<T>(controlled: T | undefined, defaultValue: T, onChange?: (value: T) => void) {

const [uncontrolled, setUncontrolled] = useState(defaultValue);

const value = controlled ?? uncontrolled;

function setValue(next: T) {

if (controlled === undefined) setUncontrolled(next);

onChange?.(next);

}

return [value, setValue] as const;

}

export function DockablePanel({

open: openProp,

defaultOpen = true,

onOpenChange,

placement: placementProp,

defaultPlacement = "right",

onPlacementChange,

finalFocus,

className,

style,

children,

"aria-label": ariaLabel = "Dockable panel",

...props

}: DockablePanelProps) {

const [open, setOpen] = useControllableState(openProp, defaultOpen, onOpenChange);

const [placement, setPlacementState] = useControllableState(placementProp, defaultPlacement, onPlacementChange);

const [dragging, setDragging] = useState(false);

const [potentialDock, setPotentialDock] = useState<DockablePanelPlacement>(placement);

const [dragPosition, setDragPosition] = useState<{ x: number; y: number } | null>(null);

const [dragHeight, setDragHeight] = useState(0);

const [announcement, setAnnouncement] = useState("");

const isMobile = useIsMobile();

const titleId = useId();

const panelRef = useRef<HTMLElement>(null);

const potentialDockRef = useRef<DockablePanelPlacement>(placement);

const dragRef = useRef<{ pointerId: number; offsetX: number; offsetY: number } | null>(null);

const returnFocusRef = useRef<Element | null>(null);

const restoreFocusRef = useRef(false);

const restoreFocus = useEffectEvent(() => {

const target = finalFocus?.current ?? returnFocusRef.current;

if (target instanceof HTMLElement && target.isConnected) target.focus();

});

useEffect(() => {

if (open) {

returnFocusRef.current = document.activeElement;

return;

}

if (!restoreFocusRef.current) return;

restoreFocusRef.current = false;

restoreFocus();

}, [open]);

function setPlacement(next: DockablePanelPlacement) {

setPlacementState(next);

setAnnouncement(`Panel docked ${next}.`);

}

function togglePlacement() {

setPlacement(oppositeDockablePanelSide(placement));

}

function close() {

restoreFocusRef.current = panelRef.current?.contains(document.activeElement) ?? false;

setOpen(false);

}

function finishDrag(event: ReactPointerEvent<HTMLElement>, shouldDock: boolean) {

if (dragRef.current?.pointerId !== event.pointerId) return;

    if (event.currentTarget.hasPointerCapture(event.pointerId)) event.currentTarget.releasePointerCapture(event.pointerId);

if (shouldDock) setPlacement(potentialDockRef.current);

dragRef.current = null;

setDragPosition(null);

setDragHeight(0);

setDragging(false);

}

function onPointerDown(event: ReactPointerEvent<HTMLElement>) {

if (event.button !== 0 || isMobile) return;

const panel = panelRef.current;

const container = panel?.offsetParent;

if (!(container instanceof HTMLElement) || !panel) return;

event.preventDefault();

event.currentTarget.setPointerCapture(event.pointerId);

const panelRect = panel.getBoundingClientRect();

const containerRect = container.getBoundingClientRect();

dragRef.current = {

pointerId: event.pointerId,

offsetX: event.clientX - panelRect.left,

offsetY: event.clientY - panelRect.top,

};

potentialDockRef.current = placement;

setPotentialDock(placement);

setDragPosition({ x: panelRect.left - containerRect.left, y: panelRect.top - containerRect.top });

setDragHeight(panelRect.height);

setDragging(true);

}

function onPointerMove(event: ReactPointerEvent<HTMLElement>) {

const drag = dragRef.current;

const panel = panelRef.current;

const container = panel?.offsetParent;

if (!drag || drag.pointerId !== event.pointerId || !(container instanceof HTMLElement) || !panel) return;

const bounds = container.getBoundingClientRect();

const nextDock = dockablePanelSideAt(event.clientX - bounds.left, bounds.width);

potentialDockRef.current = nextDock;

setPotentialDock(nextDock);

setDragPosition(

clampDockablePanelPosition(

{ x: event.clientX - bounds.left - drag.offsetX, y: event.clientY - bounds.top - drag.offsetY },

{ width: bounds.width, height: bounds.height },

{ width: panel.offsetWidth, height: panel.offsetHeight },

),

);

}

function onPointerUp(event: ReactPointerEvent<HTMLElement>) {

finishDrag(event, true);

}

function onPointerCancel(event: ReactPointerEvent<HTMLElement>) {

finishDrag(event, false);

}

const context: DockablePanelContextValue = {

close,

isMobile,

placement,

setPlacement,

togglePlacement,

titleId,

dragHandleProps: { onPointerDown, onPointerMove, onPointerUp, onPointerCancel },

};

const dropZoneStyle = dragging

? ({

height: dragHeight,

"--cui-dockable-panel-drop-zone-active-background": style?.["--cui-dockable-panel-drop-zone-active-background"],

        "--cui-dockable-panel-drop-zone-active-border-color": style?.["--cui-dockable-panel-drop-zone-active-border-color"],

} satisfies CSSProperties & DockablePanelKnobStyle)

: undefined;

if (isMobile) {

return (

<DockablePanelContext.Provider value={context}>

<Drawer open={open} onOpenChange={setOpen} side="bottom">

<DrawerContent

data-dockable-panel-root=""

data-placement={placement}

variant="floating"

surface="card"

aria-label={ariaLabel}

className={cn("max-h-[min(82vh,42rem)] gap-0 overflow-hidden", className)}

style={style}

{...props}

>

<DrawerBody padding="none">{children}</DrawerBody>

</DrawerContent>

</Drawer>

</DockablePanelContext.Provider>

);

}

if (!open) return null;

return (

<DockablePanelContext.Provider value={context}>

{dragging ? (

<>

<DockablePanelDropZone side="left" active={potentialDock === "left"} style={dropZoneStyle} />

<DockablePanelDropZone side="right" active={potentialDock === "right"} style={dropZoneStyle} />

</>

) : null}

<aside

ref={panelRef}

data-control-ui="dockable-panel"

data-control-family="dockable-panel"

data-slot="root"

data-surface="panel"

data-placement={placement}

data-dragging={dragging ? "true" : undefined}

aria-label={ariaLabel}

className={cn(

"absolute z-30 flex w-[min(22rem,calc(50%_-_1.125rem))] flex-col overflow-hidden",

!dragging && placement === "left" && "top-3 left-3 max-h-[calc(100%_-_1.5rem)]",

!dragging && placement === "right" && "top-3 right-3 max-h-[calc(100%_-_1.5rem)]",

dragging && "top-0 left-0 max-h-[calc(100%_-_1.5rem)]",

dragging && "select-none",

className,

)}

        style={dragging && dragPosition ? { ...style, transform: `translate3d(${dragPosition.x}px, ${dragPosition.y}px, 0)` } : style}

{...props}

>

{children}

<LiveStatus message={announcement} />

</aside>

</DockablePanelContext.Provider>

);

}

export function DockablePanelHeader({ className, ...props }: DockablePanelHeaderProps) {

return (

<div

data-control-ui="dockable-panel"

data-control-family="dockable-panel"

data-slot="header"

className={cn("flex shrink-0 items-center", className)}

{...props}

/>

);

}

export function DockablePanelDragHandle({

className,

onPointerDown,

onPointerMove,

onPointerUp,

onPointerCancel,

children,

dragLabel = "Drag panel",

dockHintLabel = "Drag, or use arrow keys to dock",

...props

}: DockablePanelDragHandleProps) {

const context = useDockablePanelContext();

const hintId = useId();

if (context.isMobile) {

return (

<div

data-control-ui="dockable-panel"

data-control-family="dockable-panel"

data-slot="drag-handle"

className={cn("flex min-w-0 flex-1 items-center self-stretch", className)}

{...props}

>

{children}

</div>

);

}

function dockWithKeyboard(event: ReactKeyboardEvent<HTMLButtonElement>) {

const next = dockablePanelSideForKey(event.key, context.placement);

if (!next) return;

event.preventDefault();

if (!event.repeat) context.setPlacement(next);

}

return (

<div

data-control-ui="dockable-panel"

data-control-family="dockable-panel"

data-slot="drag-handle"

      className={cn("relative flex min-w-0 flex-1 cursor-grab touch-none items-center self-stretch active:cursor-grabbing", className)}

onPointerDown={(event) => {

onPointerDown?.(event);

if (!event.defaultPrevented) context.dragHandleProps.onPointerDown(event);

}}

onPointerMove={(event) => {

onPointerMove?.(event);

if (!event.defaultPrevented) context.dragHandleProps.onPointerMove(event);

}}

onPointerUp={(event) => {

onPointerUp?.(event);

if (!event.defaultPrevented) context.dragHandleProps.onPointerUp(event);

}}

onPointerCancel={(event) => {

onPointerCancel?.(event);

if (!event.defaultPrevented) context.dragHandleProps.onPointerCancel(event);

}}

{...props}

>

{children}

<button

type="button"

data-control-ui="dockable-panel"

data-control-family="dockable-panel"

data-slot="drag-button"

aria-label={dragLabel}

aria-labelledby={context.titleId}

aria-describedby={hintId}

aria-keyshortcuts="ArrowLeft ArrowRight Enter Space"

className="pointer-events-none absolute inset-0"

onKeyDown={dockWithKeyboard}

/>

<span id={hintId} hidden>

{dockHintLabel}

</span>

</div>

);

}

export function DockablePanelTitle({ className, children, ...props }: DockablePanelTitleProps) {

const { titleId } = useDockablePanelContext();

return (

<h2

data-control-ui="dockable-panel"

data-control-family="dockable-panel"

data-slot="title"

className={cn("truncate", className)}

title={typeof children === "string" ? children : undefined}

{...props}

id={titleId}

>

{children}

</h2>

);

}

export function DockablePanelActions({ className, ...props }: DockablePanelActionsProps) {

return (

<div

data-control-ui="dockable-panel"

data-control-family="dockable-panel"

data-slot="actions"

className={cn("ms-auto flex shrink-0 items-center", className)}

{...props}

/>

);

}

export function DockablePanelToggle({ className, children, "aria-label": ariaLabel, onClick, ...props }: DockablePanelToggleProps) {

const { isMobile, placement, togglePlacement } = useDockablePanelContext();

if (isMobile) return null;

const target = oppositeDockablePanelSide(placement);

const label = `Move panel to ${target}`;

return (

<Button

type="button"

variant="ghost"

size="sm"

iconOnly

aria-label={ariaLabel ?? label}

title={label}

className={className}

onClick={(event) => {

onClick?.(event);

if (!event.defaultPrevented) togglePlacement();

}}

{...props}

>

{children ?? <DockPanelIcon side={target} />}

</Button>

);

}

export function DockablePanelDock({

placement: nextPlacement,

className,

children,

"aria-label": ariaLabel,

onClick,

...props

}: DockablePanelDockProps) {

const { isMobile, placement, setPlacement } = useDockablePanelContext();

if (isMobile) return null;

const label = `Dock panel ${nextPlacement}`;

return (

<Button

type="button"

variant="ghost"

size="sm"

iconOnly

active={placement === nextPlacement}

aria-pressed={placement === nextPlacement}

aria-label={ariaLabel ?? label}

title={label}

className={className}

onClick={(event) => {

onClick?.(event);

if (!event.defaultPrevented) setPlacement(nextPlacement);

}}

{...props}

>

{children ?? <PlacementIcon placement={nextPlacement} />}

</Button>

);

}

export function DockablePanelClose({

className,

children,

"aria-label": ariaLabel = "Close panel",

onClick,

...props

}: DockablePanelCloseProps) {

const { close } = useDockablePanelContext();

return (

<Button

type="button"

variant="ghost"

size="sm"

iconOnly

aria-label={ariaLabel}

title={ariaLabel}

className={className}

onClick={(event) => {

onClick?.(event);

if (!event.defaultPrevented) close();

}}

{...props}

>

{children ?? <CloseIcon />}

</Button>

);

}

export function DockablePanelContent({ padding = "default", className, ...props }: DockablePanelContentProps) {

return (

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

<div

data-control-ui="dockable-panel"

data-control-family="dockable-panel"

data-slot="content"

data-padding={padding}

className={className}

{...props}

/>

</ScrollArea>

);

}

function DockablePanelDropZone({

side,

active,

style,

}: {

side: "left" | "right";

active: boolean;

style?: CSSProperties & DockablePanelKnobStyle;

}) {

return (

<div

data-control-ui="dockable-panel"

data-control-family="dockable-panel"

data-slot="drop-zone"

data-surface="panel"

data-side={side}

data-active={active ? "true" : undefined}

      className={cn("pointer-events-none absolute top-3 z-20 w-[min(22rem,calc(50%_-_1.125rem))]", side === "left" ? "left-3" : "right-3")}

style={style}

/>

);

}

function PlacementIcon({ placement }: { placement: DockablePanelPlacement }) {

return <DockPanelIcon side={placement} />;

}

function DockPanelIcon({ side = "right" }: { side?: "left" | "right" }) {

return (

<svg viewBox="0 0 16 16" className="size-4" fill="none" aria-hidden="true">

<rect x="2.25" y="2.25" width="11.5" height="11.5" rx="2" stroke="currentColor" strokeWidth="1.25" />

<path d={side === "left" ? "M6 2.75v10.5" : "M10 2.75v10.5"} stroke="currentColor" strokeWidth="1.25" />

</svg>

);

}

function CloseIcon() {

return (

<svg viewBox="0 0 16 16" className="size-4" fill="none" aria-hidden="true">

<path d="m4.5 4.5 7 7m0-7-7 7" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" />

</svg>

);

}

Knobs

Typed custom properties the recipe paints with. Set one on the root — style, a utility class, or a skin — and every slot inherits it.

--cui-dockable-panel-* · 9 knobsHow the cascade resolves

--cui-dockable-panel-radius<length-percentage>

min(
      var(--radius-panel),
      calc(var(--control-h-sm) / 2 + var(--_dockable-panel-header-inset) + var(--cui-dockable-panel-border-width))
    )

--cui-dockable-panel-background<color>var(--card)

--cui-dockable-panel-foreground<color>var(--card-foreground)

--cui-dockable-panel-border-color<color>oklch(from var(--border) l c h / 0.8)

--cui-dockable-panel-border-width<length>var(--control-rim-width)

--cui-dockable-panel-shadow*var(--shadow-pop)

--cui-dockable-panel-drop-zone-active-background<color>oklch(from var(--primary) l c h / 0.12)

--cui-dockable-panel-drop-zone-active-border-color<color>oklch(from var(--primary) l c h / 0.55)

--cui-dockable-panel-drop-zone-background<color>oklch(from var(--background) l c h / 0.12)