Kappa / Floating Panel

<script setup lang="ts">
import { FloatingPanel } from "@dicehub/kappa/components/floating-panel";
import { Button } from "@dicehub/kappa/components/button";
</script>

<template>
  <FloatingPanel.Root :default-size="{ width: 340, height: 250 }">
    <FloatingPanel.Trigger as-child>
      <Button variant="outline">Open run monitor</Button>
    </FloatingPanel.Trigger>
    <FloatingPanel.Positioner>
      <FloatingPanel.Content>
        <FloatingPanel.DragTrigger>
          <FloatingPanel.Header>
            <FloatingPanel.Title>Run monitor</FloatingPanel.Title>
            <FloatingPanel.Control>
              <FloatingPanel.StageTrigger stage="minimized" />
              <FloatingPanel.StageTrigger stage="maximized" />
              <FloatingPanel.StageTrigger stage="default" />
              <FloatingPanel.Close />
            </FloatingPanel.Control>
          </FloatingPanel.Header>
        </FloatingPanel.DragTrigger>
        <FloatingPanel.Body>Run details</FloatingPanel.Body>
        <FloatingPanel.ResizeTrigger axis="se" />
      </FloatingPanel.Content>
    </FloatingPanel.Positioner>
  </FloatingPanel.Root>
</template>

Open full example (new tab)

Installation

Floating Panel is included in Kappa. Ark UI owns movement, resizing, bounds, focus restoration, stages, and panel stacking. Kappa provides the compound Vue API, compact window treatment, safe defaults, and optional Teleport.

Barrel

import { FloatingPanel } from "@dicehub/kappa";

Granular

import {
  FloatingPanel,
  FloatingPanelBody,
  FloatingPanelClose,
  FloatingPanelContent,
  FloatingPanelControl,
  FloatingPanelDragTrigger,
  FloatingPanelHeader,
  FloatingPanelPositioner,
  FloatingPanelResizeTrigger,
  FloatingPanelStageTrigger,
  FloatingPanelTitle,
  FloatingPanelTrigger,
} from "@dicehub/kappa/components/floating-panel";

Usage

Use Floating Panel for tools that must stay visible while the page behind them remains interactive. Use Dialog when work must stop until the user responds, Drawer for an edge-attached surface, and Resizable for panels that remain part of the document layout.

The Kappa root keeps dragged windows within their boundary and closes on Escape by default.
Its minimum size is 240 × 160 pixels. Ark retains the initial 320 × 240 size when no size is supplied.
Content stays mounted after close unless unmountOnExit is enabled. Set persistRect to preserve geometry across reopen.
Place interactive header content in Control or add data-no-drag.

Composition

Typical part hierarchy

FloatingPanel.Root
├── FloatingPanel.Trigger
├── FloatingPanel.Positioner + Teleport
│   └── FloatingPanel.Content
│       ├── FloatingPanel.DragTrigger
│       │   └── FloatingPanel.Header
│       │       ├── FloatingPanel.Title
│       │       └── FloatingPanel.Control
│       │           ├── FloatingPanel.StageTrigger
│       │           └── FloatingPanel.Close
│       ├── FloatingPanel.Body
│       └── FloatingPanel.ResizeTrigger × edge/corner
└── FloatingPanel.Context (optional)

Positioner owns the optional Teleport. This differs from Dialog and Drawer, where Content also creates the positioner. Keep the default Teleport and fixed strategy for viewport or application-work-area bounds. Disable Teleport only when the integration provides a matching positioning and boundary coordinate space.

Ark does not expose a controlled stage model. Use StageTrigger, the context methods, and stageChange to observe minimize, maximize, and restore operations.

useFloatingPanel is the raw Ark hook. Set the Kappa root defaults explicitly when its machine is passed to RootProvider, as shown below.

<script setup lang="ts">
import { FloatingPanel, useFloatingPanel } from "@dicehub/kappa/components/floating-panel";

const panel = useFloatingPanel({
  id: "metrics-panel",
  allowOverflow: false,
  closeOnEscape: true,
  defaultSize: { width: 360, height: 240 },
  minSize: { width: 240, height: 160 },
});
</script>

<template>
  <FloatingPanel.RootProvider :value="panel">
    <!-- Compound parts -->
  </FloatingPanel.RootProvider>
</template>

Examples

Transform tool

A compact technical window with editable content and a persistent action footer.

<script setup lang="ts">
import { ref } from "vue";
import { FloatingPanel } from "@dicehub/kappa/components/floating-panel";
import { Button, Input, Label } from "@dicehub/kappa";

const offsetX = ref("0");
</script>

<template>
  <FloatingPanel.Root persist-rect>
    <FloatingPanel.Trigger>Open transform tool</FloatingPanel.Trigger>
    <FloatingPanel.Positioner>
      <FloatingPanel.Content>
        <FloatingPanel.DragTrigger>
          <FloatingPanel.Header>
            <FloatingPanel.Title>Transform geometry</FloatingPanel.Title>
            <FloatingPanel.Control>
              <FloatingPanel.StageTrigger stage="minimized" />
              <FloatingPanel.StageTrigger stage="maximized" />
              <FloatingPanel.StageTrigger stage="default" />
              <FloatingPanel.Close />
            </FloatingPanel.Control>
          </FloatingPanel.Header>
        </FloatingPanel.DragTrigger>
        <FloatingPanel.Body>
          <Label for="offset-x">Offset X</Label>
          <Input id="offset-x" v-model="offsetX" />
          <footer data-no-drag>
            <Button variant="primary">Apply transform</Button>
          </footer>
        </FloatingPanel.Body>
        <FloatingPanel.ResizeTrigger axis="e" />
        <FloatingPanel.ResizeTrigger axis="s" />
        <FloatingPanel.ResizeTrigger axis="se" />
      </FloatingPanel.Content>
    </FloatingPanel.Positioner>
  </FloatingPanel.Root>
</template>

Controlled geometry

Bind position and size when application state must observe or restore panel geometry.

<script setup lang="ts">
import { ref } from "vue";
import { FloatingPanel } from "@dicehub/kappa/components/floating-panel";

const position = ref({ x: 56, y: 42 });
const size = ref({ width: 328, height: 244 });
</script>

<template>
  <FloatingPanel.Root v-model:position="position" v-model:size="size">
    <!-- Positioner, Content, header, body, and resize triggers -->
  </FloatingPanel.Root>
</template>

Window stages

Stage triggers minimize, maximize, and restore without adding a second window-state implementation.

<FloatingPanel.Control>
  <FloatingPanel.StageTrigger stage="minimized" />
  <FloatingPanel.StageTrigger stage="maximized" />
  <FloatingPanel.StageTrigger stage="default" />
  <FloatingPanel.Close />
</FloatingPanel.Control>

Multiple windows

Interaction raises a panel above its siblings while preserving the rest of the workspace.

<template>
  <FloatingPanel.Root default-open>
    <!-- Variables window -->
  </FloatingPanel.Root>
  <FloatingPanel.Root default-open>
    <!-- Probe chart window; interaction raises it above the first -->
  </FloatingPanel.Root>
</template>

Bounded workspace

Keep the default fixed strategy and constrain the panel to a stable application work area.

<script setup lang="ts">
import { ref } from "vue";
import { FloatingPanel } from "@dicehub/kappa/components/floating-panel";

const workArea = ref<HTMLElement>();
const getBoundaryEl = () => workArea.value ?? null;
</script>

<template>
  <main ref="workArea" class="work-area">
    <FloatingPanel.Root
      default-open
      :allow-overflow="false"
      :get-boundary-el="getBoundaryEl"
    >
      <FloatingPanel.Positioner>
        <!-- Content -->
      </FloatingPanel.Positioner>
    </FloatingPanel.Root>
  </main>
</template>

Without drag or resize

Disable gestures while retaining the non-modal window, focus, and close contracts.

<FloatingPanel.Root :draggable="false" :resizable="false">
  <FloatingPanel.Trigger>Open summary</FloatingPanel.Trigger>
  <FloatingPanel.Positioner>
    <FloatingPanel.Content>
      <FloatingPanel.Header>
        <FloatingPanel.Title>Read-only summary</FloatingPanel.Title>
        <FloatingPanel.Control><FloatingPanel.Close /></FloatingPanel.Control>
      </FloatingPanel.Header>
      <FloatingPanel.Body>Summary content</FloatingPanel.Body>
    </FloatingPanel.Content>
  </FloatingPanel.Positioner>
</FloatingPanel.Root>

Accessibility

Always render Title or provide an accessible name on Content.
Floating Panel is non-modal. It does not make the page inert or trap focus.
Content is the default focus target. Arrow keys move it when it has focus.
ResizeTrigger supports pointer input. Provide application controls that call setSize when keyboard resizing is required.
Stage and close controls include default accessible labels. Supply translated labels when the interface locale changes.
A nested Select or Popover should receive Escape before the containing panel.

Keyboard Support

Key	Behavior
`Arrow keys`	Moves the panel when Content has focus.
`Escape`	Closes the active panel when closeOnEscape is enabled.
`Tab`	Moves through controls without trapping focus in the non-modal panel.

API Reference

FloatingPanel.Root

Prop	Type	Default	Description
`open / defaultOpen`	`boolean`	`false`	Controlled or initial open state.
`position / defaultPosition`	`FloatingPanelPoint`	`—`	Controlled or initial x/y position in pixels.
`size / defaultSize`	`FloatingPanelSize`	`320 × 240`	Controlled or initial width and height in pixels.
`minSize`	`FloatingPanelSize`	`240 × 160`	Smallest permitted panel geometry.
`maxSize`	`FloatingPanelSize`	`—`	Largest permitted panel geometry.
`draggable`	`boolean`	`true`	Enables pointer dragging and content arrow-key movement.
`resizable`	`boolean`	`true`	Enables pointer resize triggers and stage changes.
`allowOverflow`	`boolean`	`false`	Allows dragging beyond the boundary when true.
`getBoundaryEl`	`() => HTMLElement \| null`	`viewport`	Returns the element that constrains geometry.
`gridSize`	`number`	`1`	Movement and resize snap interval in pixels.
`persistRect`	`boolean`	`false`	Retains geometry after close and reopen.
`closeOnEscape`	`boolean`	`true`	Closes the panel when Escape reaches it.
`strategy`	`"fixed" \| "absolute"`	`"fixed"`	Uses viewport-fixed or containing-block absolute positioning.
`disabled`	`boolean`	`false`	Disables window interaction.

Parts

Part	Element	Description
`FloatingPanel.Trigger`	`button`	Opens the panel.
`FloatingPanel.Positioner`	`div`	Owns geometry, stack order, and optional Teleport.
`FloatingPanel.Content`	`div`	Non-modal window surface and focus target.
`FloatingPanel.DragTrigger`	`div`	Pointer drag area, normally wrapped around Header.
`FloatingPanel.Header`	`div`	Compact window title bar.
`FloatingPanel.Title`	`div`	Accessible panel name.
`FloatingPanel.Control`	`div`	Header actions protected from drag gestures.
`FloatingPanel.StageTrigger`	`button`	Minimizes, maximizes, or restores the panel.
`FloatingPanel.Close`	`button`	Closes the panel; alias of CloseTrigger.
`FloatingPanel.Body`	`div`	Scrollable panel content, hidden while minimized.
`FloatingPanel.ResizeTrigger`	`div`	Pointer resize edge or corner.
`FloatingPanel.Context`	`—`	Exposes the current Ark panel API to a slot.

Events

Event	Payload	Description
`update:open`	`boolean`	Updates controlled open state.
`update:position`	`FloatingPanelPoint`	Updates controlled position during drag or movement.
`update:size`	`FloatingPanelSize`	Updates controlled size during resize.
`openChange`	`FloatingPanelOpenChangeDetails`	Reports open-state details.
`positionChange / positionChangeEnd`	`FloatingPanelPositionChangeDetails`	Reports live and committed position changes.
`sizeChange / sizeChangeEnd`	`FloatingPanelSizeChangeDetails`	Reports live and committed size changes.
`stageChange`	`FloatingPanelStageChangeDetails`	Reports minimize, maximize, or restore.

Exports

Export	Description
`FloatingPanel`	Compound component with all public parts.
`FloatingPanelRoot`	Named root export.
`useFloatingPanel`	Creates an Ark-owned panel machine for RootProvider.
`useFloatingPanelContext`	Reads panel state and imperative methods.
`FloatingPanelPoint / FloatingPanelSize`	Controlled geometry types.
`FloatingPanelStage`	The default, minimized, or maximized stage union.

Floating Panel

Run monitor

Installation

Barrel

Granular

Usage

Composition

Examples

Transform tool

Transform geometry

Controlled geometry

Controlled geometry

Window stages

Inspector

Multiple windows

Variables

Probe chart

Bounded workspace

Bounded tool

Without drag or resize

Read-only summary

Accessibility

Keyboard Support

API Reference

FloatingPanel.Root

Parts

Events

Exports