Floating Panel

A draggable, resizable panel that floats above the page. It ships with the Indoku theme applied.

Always give CloseTrigger and StageTrigger children (icons or text); they render only what you pass.

Import

tsx

import { FloatingPanel, useFloatingPanel } from "@indoku/ui"

Anatomy

FloatingPanel.Root (or RootProvider)├─ FloatingPanel.Trigger└─ Portal   └─ FloatingPanel.Positioner      └─ FloatingPanel.Content         ├─ FloatingPanel.Header         │  ├─ FloatingPanel.DragTrigger › FloatingPanel.Title         │  └─ FloatingPanel.Control › StageTrigger / CloseTrigger         ├─ FloatingPanel.Body         └─ FloatingPanel.ResizeTriggers

Examples

Basic

Root, Positioner, Content, Header, Body and ResizeTriggers.

tsx

function FloatingPanelBasic() {  return (    <FloatingPanel.Root defaultSize={{ width: 320, height: 200 }} minSize={{ width: 240, height: 140 }}>      <FloatingPanel.Trigger asChild>        <Button variant="outline">Open panel</Button>      </FloatingPanel.Trigger>      <Portal>        <FloatingPanel.Positioner>          <FloatingPanel.Content>            <FloatingPanel.Header>              <FloatingPanel.DragTrigger>                <FloatingPanel.Title>Floating panel</FloatingPanel.Title>              </FloatingPanel.DragTrigger>              <FloatingPanel.Control>                <FloatingPanel.CloseTrigger>                  <LuX />                </FloatingPanel.CloseTrigger>              </FloatingPanel.Control>            </FloatingPanel.Header>            <FloatingPanel.Body>              <Text>Drag the header to move it, pull an edge to resize.</Text>            </FloatingPanel.Body>            <FloatingPanel.ResizeTriggers />          </FloatingPanel.Content>        </FloatingPanel.Positioner>      </Portal>    </FloatingPanel.Root>  )}

Controlled open

Drive open and onOpenChange yourself.

tsx

function FloatingPanelControlled() {  const [open, setOpen] = useState(false)  return (    <HStack>      <Button variant="outline" onClick={() => setOpen((o) => !o)}>        {open ? "Close" : "Open"} (controlled)      </Button>      <FloatingPanel.Root open={open} onOpenChange={(e) => setOpen(e.open)} defaultSize={{ width: 300, height: 160 }}>        <Portal>          <FloatingPanel.Positioner>            <FloatingPanel.Content>              <FloatingPanel.Header>                <FloatingPanel.DragTrigger>                  <FloatingPanel.Title>Controlled</FloatingPanel.Title>                </FloatingPanel.DragTrigger>                <FloatingPanel.Control>                  <FloatingPanel.CloseTrigger>                    <LuX />                  </FloatingPanel.CloseTrigger>                </FloatingPanel.Control>              </FloatingPanel.Header>              <FloatingPanel.Body>                <Text>open = {String(open)}</Text>              </FloatingPanel.Body>            </FloatingPanel.Content>          </FloatingPanel.Positioner>        </Portal>      </FloatingPanel.Root>    </HStack>  )}

Stage triggers

minimized, maximized and default.

tsx

function FloatingPanelStages() {  return (    <FloatingPanel.Root defaultSize={{ width: 340, height: 200 }}>      <FloatingPanel.Trigger asChild>        <Button variant="outline">Open with stage triggers</Button>      </FloatingPanel.Trigger>      <Portal>        <FloatingPanel.Positioner>          <FloatingPanel.Content>            <FloatingPanel.Header>              <FloatingPanel.DragTrigger>                <FloatingPanel.Title>Stages</FloatingPanel.Title>              </FloatingPanel.DragTrigger>              <FloatingPanel.Control>                <FloatingPanel.StageTrigger stage="minimized">                  <LuMinus />                </FloatingPanel.StageTrigger>                <FloatingPanel.StageTrigger stage="maximized">                  <LuMaximize2 />                </FloatingPanel.StageTrigger>                <FloatingPanel.StageTrigger stage="default">                  <LuMinimize2 />                </FloatingPanel.StageTrigger>                <FloatingPanel.CloseTrigger>                  <LuX />                </FloatingPanel.CloseTrigger>              </FloatingPanel.Control>            </FloatingPanel.Header>            <FloatingPanel.Body>              <Text>Minimize, maximize or restore the panel.</Text>            </FloatingPanel.Body>            <FloatingPanel.ResizeTriggers />          </FloatingPanel.Content>        </FloatingPanel.Positioner>      </Portal>    </FloatingPanel.Root>  )}

Store provider

Create the store with useFloatingPanel and pass it to RootProvider.

open: false

tsx

function FloatingPanelStore() {  const panel = useFloatingPanel({ defaultSize: { width: 300, height: 170 } })  return (    <>      <HStack wrap="wrap">        <Button variant="outline" onClick={() => panel.setOpen(true)}>          Open        </Button>        <Button variant="outline" onClick={() => panel.maximize()}>          Maximize        </Button>        <Button variant="outline" onClick={() => panel.minimize()}>          Minimize        </Button>        <Button variant="outline" onClick={() => panel.restore()}>          Restore        </Button>        <Text fontSize="sm" color="fg.muted">          open: {String(panel.open)}        </Text>      </HStack>      <FloatingPanel.RootProvider value={panel}>        <Portal>          <FloatingPanel.Positioner>            <FloatingPanel.Content>              <FloatingPanel.Header>                <FloatingPanel.DragTrigger>                  <FloatingPanel.Title>Store provider</FloatingPanel.Title>                </FloatingPanel.DragTrigger>                <FloatingPanel.Control>                  <FloatingPanel.CloseTrigger>                    <LuX />                  </FloatingPanel.CloseTrigger>                </FloatingPanel.Control>              </FloatingPanel.Header>              <FloatingPanel.Body>                <Text>Driven from outside via useFloatingPanel.</Text>              </FloatingPanel.Body>            </FloatingPanel.Content>          </FloatingPanel.Positioner>        </Portal>      </FloatingPanel.RootProvider>    </>  )}

Boundary constraints

Keep the panel inside an element with getBoundaryEl.

The panel cannot leave this box.

tsx

function FloatingPanelBoundary() {  const boundary = useRef<HTMLDivElement>(null)  return (    <Box ref={boundary} position="relative" h="280px" borderWidth="1px" rounded="md" borderStyle="dashed" p="3">      <Text fontSize="sm" color="fg.muted">        The panel cannot leave this box.      </Text>      <FloatingPanel.Root        defaultOpen        defaultSize={{ width: 220, height: 130 }}        getBoundaryEl={() => boundary.current}        defaultPosition={{ x: 20, y: 60 }}      >        <FloatingPanel.Positioner>          <FloatingPanel.Content>            <FloatingPanel.Header>              <FloatingPanel.DragTrigger>                <FloatingPanel.Title>Bounded</FloatingPanel.Title>              </FloatingPanel.DragTrigger>            </FloatingPanel.Header>            <FloatingPanel.Body>              <Text>Try dragging me out.</Text>            </FloatingPanel.Body>            <FloatingPanel.ResizeTriggers />          </FloatingPanel.Content>        </FloatingPanel.Positioner>      </FloatingPanel.Root>    </Box>  )}

Anchor positioning

Compute the starting position with getAnchorPosition.

tsx

function FloatingPanelAnchor() {  return (    <FloatingPanel.Root      defaultSize={{ width: 260, height: 140 }}      getAnchorPosition={({ triggerRect }) =>        triggerRect ? { x: triggerRect.x, y: triggerRect.y + triggerRect.height + 8 } : { x: 100, y: 100 }      }    >      <FloatingPanel.Trigger asChild>        <Button variant="outline">Opens below me</Button>      </FloatingPanel.Trigger>      <Portal>        <FloatingPanel.Positioner>          <FloatingPanel.Content>            <FloatingPanel.Header>              <FloatingPanel.DragTrigger>                <FloatingPanel.Title>Anchored</FloatingPanel.Title>              </FloatingPanel.DragTrigger>              <FloatingPanel.Control>                <FloatingPanel.CloseTrigger>                  <LuX />                </FloatingPanel.CloseTrigger>              </FloatingPanel.Control>            </FloatingPanel.Header>            <FloatingPanel.Body>              <Text>Positioned from the trigger rect.</Text>            </FloatingPanel.Body>          </FloatingPanel.Content>        </FloatingPanel.Positioner>      </Portal>    </FloatingPanel.Root>  )}

Props

FloatingPanel.Root

Prop	Type	Default	Description
`open`	`boolean`	–	Controlled open state.
`defaultOpen`	`boolean`	`false`	Initial open state.
`onOpenChange`	`(details: { open: boolean }) => void`	–	Called when the panel opens or closes.
`onStageChange`	`(details: { stage: 'minimized' \| 'maximized' \| 'default' }) => void`	–	Called when the stage changes.
`defaultSize / size`	`{ width: number; height: number }`	–	Initial or controlled size.
`minSize / maxSize`	`{ width: number; height: number }`	–	Resize limits.
`defaultPosition / position`	`{ x: number; y: number }`	–	Initial or controlled position.
`getBoundaryEl`	`() => HTMLElement \| null`	–	Element the panel is constrained to. Defaults to the viewport.
`getAnchorPosition`	`(details: { triggerRect, boundaryRect }) => { x: number; y: number }`	–	Computes the position when the panel opens.
`draggable / resizable`	`boolean`	`true`	Turn dragging or resizing off.
`lockAspectRatio`	`boolean`	`false`	Keep the aspect ratio while resizing.
`persistRect`	`boolean`	`false`	Remember size and position between opens.

FloatingPanel.StageTrigger

Prop	Type	Default	Description
`stage*`	`'minimized' \| 'maximized' \| 'default'`	–	Stage this trigger switches to.

useFloatingPanel (store)

Prop	Type	Default	Description
`open / setOpen(open)`	`boolean / fn`	–	Read or set the open state.
`minimize() / maximize() / restore()`	`() => void`	–	Change the stage.
`setPosition(pos) / setSize(size)`	`fn`	–	Move or resize programmatically.

* required. Style props and HTML attributes are accepted as well.

Accessibility

The title is wired to the content with aria-labelledby.
Give icon-only triggers an aria-label.

Notes

Render Positioner inside a Portal so the panel is not clipped by overflow containers.
With getBoundaryEl, the boundary should be position: relative.

← Dialog Clipboard →

Created by @indokudev