# Floating Panel

A movable, resizable window beside the page that floats, docks to the side, goes full screen or minimises to a bar.

- Category: Navigation & Layout
- Page: https://wunderui.com/components/floating-panel
- Tier: Core and Pro

## Install

Floating Panel ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { FloatingPanel, FloatingPanelBody, FloatingPanelHeader, FloatingPanelHeaderProps, FloatingPanelMode, FloatingPanelProps } from "@wunderui/react"
```

## Anatomy

- `FloatingPanel`: A dialog fixed to the viewport, rendered into the document body. Floating it is a 16 px rounded card with the xl shadow, 400 × 480 in the bottom-right corner; docked it fills the height at the end edge; full screen it covers the window and holds focus; minimised it becomes a bar.
- `FloatingPanelHeader`: A 48 px row with the title, your actions and the mode buttons. FloatingPanel renders it from `title`; render your own only without `title`.
- `Handle`: The title area. While floating it moves the panel with the pointer, or with the arrow keys when focused (16 px, Shift 64 px), and announces the new position.
- `Mode buttons`: Ghost icon buttons, size sm: dock or float, full screen or exit full screen, minimise and close. The icons are the IconProvider roles dock, undock, expand, collapse, minimize and close.
- `FloatingPanelBody`: The scrolling content with 16 px padding.
- `Resize handle`: A 24 px button in the bottom-right corner while floating. Drag it or use the arrow keys; the size stays between minSize and the window.
- `Minimised bar`: A 44 px bar 16 px from the bottom-right corner with the title (restores the panel) and a close button. The panel's content stays mounted while minimised.
- `Floating Panel`
- `Restore`

## Best practices

### When to use

- Use a Floating Panel for work that runs beside the page and is visited more than once: notes, a chat, a viewer. For a task that blocks the page use a Dialog; for a detail view tied to one row use a Sheet.

### Do

- Give it a short title. It names the dialog for screen readers and labels the minimised bar.
- Pass a storageKey when the panel is reopened often, so it comes back where the person left it.
- Keep drafts in the panel's content: minimising keeps it mounted, closing unmounts it.
- Inside a themed frame, pass container (an element in the frame) so the frame's CSS variables reach the panel and its bar; barClassName and barStyle style the minimised bar.

### Don't

- Don't open several floating panels at once; minimised bars sit in the same corner and cover each other.
- Don't put a second close or minimise button in actions; the header already has them.

## API reference

### FloatingPanel

| Prop | Type | Default | Description |
|---|---|---|---|
| actions | React.ReactNode |  | Extra header buttons, placed before the mode buttons. |
| barClassName | string |  | Classes for the minimised bar (the panel itself takes `className`). |
| barStyle | React.CSSProperties |  | Inline style for the minimised bar, e.g. the same CSS variables as the panel's `style`. |
| children | React.ReactNode |  | The panel's content, usually a FloatingPanelBody. Without `title`, start with your own FloatingPanelHeader. |
| container | HTMLElement \| null |  | Where the panel and its minimised bar render (a portal). Default `document.body`. Pass an element inside your frame so the frame's CSS variables and scoped styles reach them; while it is `null` (a ref not set yet) nothing renders. |
| defaultMode | "floating" \| "docked" \| "fullscreen" \| "minimized" | "floating" | Mode on first render when uncontrolled. Default `floating`. |
| defaultOpen | boolean | true | Open on first render when uncontrolled. Default true. |
| defaultPosition | Point |  | Top-left corner in viewport pixels while floating. Default: the bottom-right corner, 16 px from the edges. |
| defaultSize | Size | DEFAULT_SIZE | Size while floating (the width also applies when docked). Default 400 × 480. |
| minSize | Size | MIN_SIZE | Smallest size the corner handle allows. Default 320 × 240. |
| mode | "floating" \| "docked" \| "fullscreen" \| "minimized" |  | Controlled mode. |
| onModeChange | (mode: FloatingPanelMode) => void |  |  |
| onOpenChange | (open: boolean) => void |  |  |
| open | boolean |  | Controlled open state. |
| storageKey | string |  | Remembers position, size and mode in localStorage under this key. |
| title | React.ReactNode |  | Heading of the panel (also its accessible name and the label of the minimised bar). |

Also accepts React.HTMLAttributes attributes.

### FloatingPanelBody

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### FloatingPanelHeader

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  |  |
| actions | React.ReactNode |  | Extra buttons before the mode buttons (keep them to icon buttons, size sm). |
| modes | readonly Exclude<FloatingPanelMode, "minimized">[] | ["floating", "docked", "fullscreen"] | Mode buttons to offer. Default all three. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Actions: extra buttons in the header

### Size: where it starts and how small it can get

## In context

### Meeting notes that remember their place

With a storageKey the panel keeps its position, size and mode, so the notes open where they were left after a reload.

## For AI agents

`get_component("floating-panel")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
