Floating Window

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add floating-window

Usage#

import { FloatingWindow, FloatingWindowLayer } from "@/components/ui/floating-window"

export function Example() {
  const [win, setWin] = React.useState({ x: 2, y: 2, width: 24, height: 16 })
  return (
    <div className="relative h-screen">
      <FloatingWindowLayer>
        <FloatingWindow
          title="Unit 12"
          {...win}
          onMove={(x, y) => setWin((w) => ({ ...w, x, y }))}
          onResize={(width, height) => setWin((w) => ({ ...w, width, height }))}
        >
          <UnitDetails />
        </FloatingWindow>
      </FloatingWindowLayer>
    </div>
  )
}

Anatomy#

import { FloatingWindow, FloatingWindowLayer } from "@/components/ui/floating-window"

<FloatingWindowLayer>
  <FloatingWindow title="…" x={…} y={…} width={…} height={…}>
    …
  </FloatingWindow>
</FloatingWindowLayer>

Managing windows#

The window is controlled: it reports a drag through onMove(x, y) and a resize through onResize(width, height), already kept inside the layer and above the minimum, and draws whatever you pass back. The z-order is yours too: give each window a zIndex and raise it in onFocusWindow, which fires when the window is pressed anywhere or focus moves into it from outside. A few lines of state are the whole window manager.

function useWindows(initial: Win[]) {
  const [windows, setWindows] = React.useState(initial)
  const top = React.useRef(initial.length)
  const patch = (id: string, change: Partial<Win>) =>
    setWindows((ws) => ws.map((w) => (w.id === id ? { ...w, ...change } : w)))

  return {
    windows,
    focus: (id: string) => patch(id, { zIndex: ++top.current }),
    move: (id: string, x: number, y: number) => patch(id, { x, y }),
    resize: (id: string, width: number, height: number) => patch(id, { width, height }),
    toggle: (id: string) =>
      setWindows((ws) => ws.map((w) => (w.id === id ? { ...w, minimized: !w.minimized } : w))),
    close: (id: string) => setWindows((ws) => ws.filter((w) => w.id !== id)),
  }
}

Minimize and controls#

minimized folds the window up to its title bar, like a window shade. Its content stays mounted (a half-written note survives) and turns inert until it unfolds. The bar shows a control only for a handler you pass: onToggleMinimize adds the minimize button and the double-click on the bar, onClose adds the close button. Double-click the folded bar below.

Sizing in rem#

x, y, width, height, minWidth (18 by default) and minHeight (4.25: the bar and 2rem of content) are all rem, so a UI that scales by changing the root font size scales its windows with it. The pointer is converted with the root font size read when a drag starts. A move keeps 6rem of the window inside the layer on the left (the controls) and 4rem on the right, and the bar never leaves the top or bottom; a resize stops half a rem short of the layer's far edges. Without a FloatingWindowLayer around it, a window is unbounded.

API reference#

FAQ#